Why Write Code Comment ?

comments-in-codeToday we are going to focus on why write code comment. Now, after searching for code comment on Google, it is very interesting to note that there are two sides in code comment. Those in favor of code comment and those in favor of readable code. So, why write code comment ?

Alex Allain summarizes the point for code commenting nicely:

But readable code, while a nice ideal, often requires some help from the English (or from some other) language. Sometimes the algorithm is too complex to be understood rapidly or completely without some explanation, or the code requires some esoteric function call from the C library that has both a cryptic and a misleading name. And if you ever plan to code for a living, you will almost certainly have to go back several years later to modify the one section of code that you didn’t feel like commenting — or someone else will, and will curse your name. Finally, commenting code can also lead to a better understanding of the program and may help uncover bugs before testing. For both aesthetic and practical reasons, good commenting is an essential and often overlooked programming skill.

Source: C Programming

Four points from Alex on reasons for code comment :

  • Readable code have weak points.
  • Complex algorithm makes code comment a necessity
  • Use of other people library also requires code commenting
  • Better understanding of the program
  • Help remember old code

Next, the most important use of code comment is to help understand WHY the code is written in a certain way, not HOW the code was written.

I’m constantly running across comments from developers who don’t seem to understand that the code already tells us how it works; we need the comments to tell us why it works.

Source: Coding Horror

Now, programming languages have come a long way to make readable code a reality and some people stand by it. But, good old comment still have its place.