In this days i read a discussion on a forum between some programmers and they were discussing about "Write or not to write comments on programs".
The discussion result wasn't so obvious, because many of them said that comments were not only useless, but also dangerous, and in the most of cases it would be better if they weren't ever written.
This is an example of bad comments:
channel++; //increment channel
The good thing about this line was that both the code and the comment agreed (experience shows this is quite often not the case). The bad thing about this code is that they are both wrong, the problem being that the original coder didn't understand the difference between channel and timeslot [2] and chose the wrong variable name. Fortunately, when he (or someone who came along later) realised the mistake he used a snazzy re-factoring tool that avoids the problems with global
"find and replace" and understands the code enough to only change the relevant variable name and not other occurrences of the string or the same name in another scope. The code now reads:
timeslot++; //increment channel
You might ask why the re-factoring programmer didn't change the comment to match and it was because he wasn't looking at that particular line, but at this one:
uint32_t channel; // I think this is probably timeslot, not channel.
The first person to come along realised the poor choice of variable name and "fixed" it by adding a comment. The second decided it would be better to change the variable name. Obviously, the second programmer believes in saying it in the code and disregarding comments, because the changed line now reads:
uint32_t timeslot; // I think this is probably // timeslot, not channel.
So what's the truth about comments? is it better to write them or not ?
Another example can be this:
r = n / 2;
while ( abs( r - (n/r) ) > t ) {
r = 0.5 * ( r + (n/r) );
}
System.out.println( "r = " + r );
Any idea what that bit of code does? It's perfectly readable, but what the heck does it do? Let's add a comment.
// square root of n with Newton-Raphson approximation
r = n / 2;
while ( abs( r - (n/r) ) > t ) {
r = 0.5 * ( r + (n/r) );
}
System.out.println( "r = " + r );That must be what I was getting at, right? Some sort of pleasant, middle-of-the-road compromise between the two polar extremes of no comments whatsoever and carefully formatted epic poems every second line of code? Not exactly. Rather than add a comment, I'd refactor to this:
Codice:
private double SquareRootApproximation(n) {
r = n / 2;
while ( abs( r - (n/r) ) > t ) {
r = 0.5 * ( r + (n/r) );
}
return r;
}
System.out.println( "r = " + SquareRootApproximation(r) );I haven't added a single comment, and yet this mysterious bit of code is now perfectly understandable.
This guy (
http://www.makinggoodsoftware.com), that got a blog where he writes about tips to make a good code, wrote an interesting page on "writing comments or not", and you can find his article here:
http://www.makinggoodsoftware.com/2009/06/06/comments-are-evil/
where he basically says that:
- The worst code is: Bad code without comments.
- Bad code is: Bad code with comments.
- The average code is: Average code with comments.
- Good code is: Good code with a few comments…
- …but… Great code doesn’t need comments!!!
And he gives some advices on how to increase the readiblilty:
http://www.makinggoodsoftware.com/2009/06/22/how-to-write-readable-code/
and
http://www.makinggoodsoftware.com/2009/06/04/10-commandments-for-creating-good-code/
It's important to keep improving our code, to help us and other people mantaining the applications.
