Even Code Comments, Are Very Important!

The story was started by this email:

All,

Please, allow me to share a little bit.

I have just read the Programming Standards.doc, and I found out something interesting in the document about code comments (all of you might have known this). I have highlighted some statements that might important to be concerned when writing our codes.

You can find the complete standard in Programming Standards.doc.

... Some paragraphs has been deleted...

By reading this, I become more realized that even comments in code have a standard for our client. Overall, I think to follow this standard there is no other way except trying to follow them when writing our codes in each task (And I am still trying to do so).

Any input, please welcome.

Regards,

-imsuryawan-

Above, was my email a couple days ago to all team members about code comments. Yes, I know this is an old topics for the one who have been involved in Programming for long years. But, still... for a newcomers, this is a very good stuff to know.

I remember when I was at the first time involved in a professional team who worked as an outsourced Software Engineers for a well known company in Australia, that code comments is very important. My senior who was being my code reviewer, writes a huge bunch notes about my comments. That time I was thinking, "Man, this is just a comment. The compiler will never care about them! So, what's wrong with this?". Hahaha... Please understand, I was still a Junior SE that time. :D

Now, I am a senior programmer in a different outsourced team for the same client. After reading the Programming Standard I become more realized that event code comments are a very important thing to be concerned, so they write them in the document.

I am sorry that I can not tell you what the rules in the document are. Overall, most of the item written in the document is a common rule when writing code comment. There are so many articles on the net about how to write a good code comment. This one is a good reference for you. Other source maybe by reading Code Complete by Steve McConnel - which discussing how to create a self documenting codes in chapter 32.

So, let's start to write a good comments in our codes. :D