Essential Skill for Agile Developmet (Turning Comments into Code)

I started reading this book and find it quiet good in the way it clear show you how to improved your development skills in a very simple way.

Today im reading the following chapter 2: "Turning Comments into Code".

How often we find outdated comments in the code, how often do we find useless comments in the code.

Basically this chapter tells you that if would be better insteads of putting a comments side by side with the code, just to make the code as clear as the comments itself. i.e:

public class ParticipantInfoOnBadge {
String pid; //participant ID
String engName; //participant's full name in English
String chiName; //participant's full name in Chinese
String engOrgName; //name of the participant's organization in English
String chiOrgName; //name of the participant's organization in Chinese
String engCountry; //the organization's country in English
String chiCountry; //the organization's country in Chinese
...
}

this could be written like:

public class ParticipantInfoOnBadge {
String participantId;
String participantEngFullName;
String participantChiFullName;
String engOrgName;
String chiOrgName;
String engOrgCountry;
String chiOrgCountry;
}


As you can see the code itself is clear enough to understand the meaning on each fields, even thought i could place a lot of examples showing where comments are not worth, i would rather prefer you to read the book.

Let me cite a paragraph from the chapter that clearly shows what the author is trying to teach us:

Why delete the separate comments?
In fact, comments by themselves are not bad. The problem is that we often
do not write clear code (because it is hard), so we take a shortcut
(use comments) to hide the problem. The result is, nobody will try to make
the code clearer.

Later, as the code is updated, commonly nobody updates the comments
accordingly. In time, opposed to making the code easier to read,
these outdated comments will actually mislead the readers. At the end of
the day, what we have is: Some code that is unclear by itself, mixed with
some incorrect comments.