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


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.

cheap replica watches said...

Why is that will consequently? Should you look at the impressive ladies "Vivante" collection, you'll learn why. Regardless of whether these kind of watches are saved to your current wrist or even anywhere else, they're just stunning. They even make these showcasing in the new steel or discount fake Omega watches UK even buckskin group. Their dials are produced from mother-of-pearl and yet another expensive models occur adorned together with replica Tag Heuer watches precious treasures. Business owners must put faux montres omega on a Imitation de qualite Bell & Ross model designed for ornate show. Their own business spouses and also buyers holds an excellent effect which after they use the actual "Ambassador" distinct watches. For the athletes, the "Active" brand of wrist watches is great for them. Chosen of the timepieces could run as much as 330 legs underwater. replica Balenciaga Classic handbags

Post a Comment