Writing Better Comments in Code

Tuesday, August 24, 2010

Writing Better Comments in Code

Writing CommentsThis is not copied from anywhere, this is from my experience. So, it may be wrong, take it with a pinch of salt (or sugar or whatever).

As everyone would say, commenting is an art, like anything else... here we go... I will be too open, please don't take everything as it is said... think before you comment...

Why do we write comments? We write comments to define what we are going to do, so that we don't lose focus. We write comments so that we don't forget to fix something (we normally use FIXME or TODO). We write comments so that we would be able to catch up with the flow when we get old and we come back to the code. If you ask me, I would say, "I am not gonna put comments so that someone I have never met will be able to manage my code when I am dead, I don't care". But I comment because I like my code to look good and understandable (I do a lot more than comments for that). I have seen lot of people starting their code with just lot of comments and then filling in the code based on what the comment says. That is an excellent way of coding, but tedious. We always want to see our code running first than to see our code looking good. That brings us back to coding, which is one of the greatest arts ever invented by man, be an artist. Enough of philosophy, let's get to work...

When we do coding, when we write a statement, there is lots of information already there, the name of the file, the name of the function the statement is in, the statement body itself, these all contains valid useful information. Then why do we need comments. "We need comments to augment the information already there." Yes, we want to add more information than what already exists. But, "comments should NOT repeat or conflict the information already there." So, that is the main philosophy of comments. But, there is a contradiction, as I mentioned earlier, sometimes we take pseudo code from design and add them as comments before coding, in that case, the comment will duplicate the code, that is one exception to the rule.

Let's look into detail... If the file name contains the name of the module, module name should NOT be there in the comment. Comment should NOT contain the name of the function. If the function name explains what is happening, no need of comment. Comment should never contain words like function, subroutine etc to show that the comment is for a function.

"Comment should NOT mention how we reached here." You heard me right, don't comment saying we are executing this function because two years back a black king ruled Africa. When we are reading a comment, we should know why we are here, that is for us to figure out. We sometimes have a section called "Called from" in function banners, that is the extend I would ever go.

Try to "verbalize your thought process through comments." Just put whatever you are thinking into the comment, just write down any questions you ask to yourself (that will normally be followed by a conditional statement), don't worry about comments being non-technical, don't worry about comments not having quality English, don't worry about grammar or punctuation, just write down what you feel... but there is a catch, if you become too personal, someone else won't be able to follow your thoughts... two words... "clear & simple"... that will do...

We always get confused whether to comment or not. Always think from the viewpoint of the youngest member in your team... if that member can understand the statement without a comment, then you don't need one...

"Comments are never enough." There is nothing called too much comments. I have seen comments with a couple of paragraphs for a function having 5 lines of code, that is a little too extreme, but I never thought he is crazy, because he just wants to convey every detail... So, never be a miser when commenting.

That will do for now...

Comments are welcome :)

See also... » gccgo - another Google Go compiler - Part 1

» Google Go - A First Look

» Booting Ubuntu 9.10 - Part 1 (The Downfall)

» Effective Use of VIM - Part 1

» Mounting FAT32 Partitions with Full User Permission in Ubuntu

» Yahoo Messenger! in Ubuntu


ATOzTOA : Latest Headlines


2 comments:

Peter Jones said...

Your article is nice, I read your article to learn a lot and hope to see your next article,replica miu miu look forward to your masterpiece, you can also see our ball gowns information,christian louboutin replica I hope it can give you You some convenient.

Post a Comment