Thursday, September 2, 2010

Commenting about Comments

//TODO : Finish this rant
#There has been a lot of discussions about the use of comments that appear in program code. This was something that I overlooked so far and only used when it appealed to me, which is itself a rare occasion for me.

#In the book, '97 things every programmer should know', there have been a lot of insight over the same issue. In it, Carl Evans recollects a lesson that he learned from his teacher(getting poor grades without commenting). The same thing, in fact happened to me too.

#Recently, a lecturer teaching Software Engineering (who is quite vociferous in his teachings)in our class proclaimed, “Comments are just waste of time and people(coders perhaps ?) should be kicked in their ass for writing comments. Comments indicate that the programmer was wasting time in writing them instead of writing LOCs”.
However, I learned a lesson similar to Carl in my class exams held in the previous week. In the exam, there was a question that required us to print a pascaline triangle using C#. I wrote its program, that I conjured up at the moment and hoping that it'll yield returns in terms of marks. But to my utter surprise, the program in question was awarded a big 0.
While explaining the paper, this teacher(who teaches .NET framework and C#) declared the opposite of the commenting practices listed above.
In my opinion, the amount of comment that you really need to insert is when the code requires some external prodding to be able to be understood.

So, I guess that it is probably useful to create and maintain comments in a codebase if it is self-describing. According to me, for long term basis a comment should only written specifically for technical documentation. The use of javadocs or msdn styled comments not only serve the purpose for the ordinary comments, but also aid future developers into maintaining and extending the software as they can provide insight in various ways( separate documentation and IDE support).

In The Elements of Programming Style (Computing McGraw-Hill), Kernighan and Plauger note that “a comment is of zero (or negative) value if it is wrong.”. These, alongwith my thoughts over the usability and proportionality of comments are echoed in this javaranch discussion thread. Hopefully, in the near future such a situation may not arise when it became an embarrassing situation for me, just because of lack of comments in my otherwise correctly functioning piece of code.

No comments: