Programming Rules of Thumb – On Comments

Duncan Merrion, the original author of the seven rules, left a comment on my previous post :

The secret to investing is “buy low, sell high”. (Also, the secret to carpentry is “measure twice, cut once” ) – this doesn’t mean if you only do this you will be a successful investor (or carpenter) but rather that if you are a successful investor (or carpenter) you will do this as a habit.

This is what i was aiming for with the 7 secrets article – although much subsequent reading (it was written about 5 years ago) has convinced me that hungarian notation is not a good thing at all, and the comment often, comment well paragraph needs to be rewritten but I still stand by the article as a whole.

Ok. I’m sure we can all find somthing to trash about  someone else’s philisophy, specially when it comes to programming. I myself prefer doing the user interface first. That gives me a clear idea of how my how my data structures will work.Not that ialwyas do that. The UI and the data classes usually evolve at the some time. I find a probelem i one that requires a twaek in the other. Not everyone would agree with that. Some would have it that as a process: one does the data, the other does the UI and still another ties it all together.  So esentially we al have our own philosphy. This can and oes change moving programming language. Visual Basic 2005 is nearly english. All you have to do is pick the right variable and function names and you’re most of the way to self documenting code. C/C++ and even C# to an extent have different syntax to Vb2005 and require more commenting. But on the whole, comments are extremely useful. There are times when a function or a procedure is simply too complex. This is especially the prblem in C/C++ as the amount of things you can do on a simgle line is far greater than VB. In VB you van have a series of function calls that return data to the next function

i.e x= Function1(function2(function3())).

Not that that is the best way of doing it. But that is what sometimes happens. If you change it to sothing more readable. I’ll take Pythagoras as an example :

 a = calculatedistance(Squarepoints(getpointsBC()))

And viola: readable code. And to an extent, self documenting. What are the points being retunrned. What distance is it getting. Why? All this can be put into the comments. The code surrounding this line might well explin it. so its a 50/50 solution that changes from programmer to programmer. It might be helpful siomply to add comments once the program is completed for others to read ( or for you to read come maintanence time).

Duncan metions some of this in his post that he reffered me to. So, as he puts all the above:

Additionally the source code is only self-documenting to someone who has a good knowledge of the programming language that the source code is written in. However it is often the case that the person who has the best understanding of the problem space (be they a business analyst, end client or whatever) does not have sufficient developer experience to be able to read the code itself.

A good comment states the intent of the code to which it applies in the language of the problem domain but does not describe the computation operations being performed.

I completely forgot the other reason he gives for comments. The fact that the expert in the problem sapce, as he puts it, needs tro be able to understand what the code is doing, rather than the code itself. A Mathematitian would express Pythagoras as a(squared) = b(squared)+ c(squared). Although the function names above are descriptive ( since the function names are there to remind us of the job they are doing, rather than their internal workings), the above mentioned math geek would have to be told that htta’s what this line of code is doing- commets. Thus a mathematitiance would undersand Pythagoras as:

The math geek is happy becuase he knows whats going on and can make sure the function works .

All the seven Rules needs is a title change and a change of perspective: they are tips, not royal decrees (or NFL rules). The article highlights seven areas that programmers find helpful in certain situations. We could go into enormous detail about the ins and outs of progrgramming and turning out good code. But, with alittle updataing ( the article is five years old), it’ll do the article a world of a difference.