Delphi Programming

and software in general.

Thursday, August 7, 2008

Writing readable code - Comment for Context

While waiting for more suggestions to Paul's snippet, and while weaving and dodging through the virtual fireballs from the previous posts on code formatting and comments, I fearlessly continue my Don Quixote Crusade for readable code. I am not quite done with comments yet.

It is said that "Real programmers don't write comments - It was hard to write - it should be hard to read". That doctrine is way overdue for deletion.

Comments are the context frame of our code.

Comments are like garlic.
Too little and the result is bland and unpalatable, too much and it stinks things up. Comments should only in rare occasions assume that the reader is too dumb to read the code properly, so as a general rule - we should not rewrite our code in plain english, line for line. Such an approach tend to fog up [sic] the source, and it becomes a drag to maintain (Yeah, I know... garlic metaphors stink...).

Comments are like news headlines.
// File ready for saving!
// No more filehandles, says OS
// Raises exception for World+dog
They should be short, concise and to the point. In good tabloid tradition, they should also only touch on the very general points, and oversimplifying what really is going on.

Comments are like foreplay.
They serve to get us readers in the mood to appreciate the sleek lines, the richness of it's properties, and possibly arouse our interest to the point where we are ready to ravage the code.

Comments are like, bi-se... uh directional.
Err, well ... what I am trying to say is that sometimes we can write them before we do stuff, while at other times - it can be just as effective to write them after something has been done in the code. The first would probably indicate how we are going to do something, while the latter would focus on the result of what we just did.

Pick up the garbage!
Do you leave your workshop tools lying about in case you need them quickly, or do you store them safely away? Once you finalize your code, clean it up. Put "I deleted this, moved that, added that" comments in your version control commit/check-in comments, and don't litter the source code with it. Once the code has been created or removed, the reason is uninteresting. What the code is supposed to do, is so much more valuable information. Remove unnecessary comments.

Don't spread FUD.
Your commentary should embellish the correctness and function of your code, not underline how insecure, unexpectedly behaving, mysterious, or potentially unreliable code it is. If there is remaining work to be done, that should be written as a To-Do point, containing sufficient information to guide you to a starting point for that work.

It takes practice to write good commentary (life-long practice, some would say), but unless your code is totally clear and unambiguous to the point of self-explaining to your grandmother, you should probably add some comments.

To round it off, here are a couple of disturbing - but funny - comments I have come across in production code:

// ---- Better let sleeping dogs lie? Note the date. ----

try
if ValidParentForm(self) <> nil then
begin
ValidParentForm(Self).ActiveControl:=NIL;
//Turn this back on when I return from my holiday and have time to test it
//N.N. 20.07.2001
{if ValidParentForm(Self).ActiveControl=lFocusedControl then
//Control doesn't let go of focus, most likely because of some error message
exit; //Aborting the routine}
end;
if DataSet is TExtendedDataSet then
TExtendedDataSet(DataSet).Save
else
DataSet.Post;
finally
. . .

// ---- Unusual if/then/else construct ----

if (EditSomeProp.Text <> '')
and ((RequestTable[i].NUMREF+1) > StrToInt(EditSomeProp.Text)) then
// Watch out for Elsie here
else
begin
. . .
Should I or should I not uncomment the first comment? Well, it has been inactive for 7 years, so I think I'll leave it as is, or remove it.
The second one is history, due to a rewrite.