Tuesday, January 22, 2008

comments required!

Got a nice feedback the other day from a client. They had a code review of my work and they appreciated the level of comments in the code.

I'm a die hard fan of comments in the code. There are two common arguments against comments in code.
- code should easy to read
- comments becomes out of date to the code (more stuff to maintain)

These arguments has some merit. Code should be easy to read, meaningful variable names, etc. But that's not an excuse for not commenting the code. Good code is not a substitute for good comment. Good comments made good code great.

Comments do become out of date to the code, and it's confusing when the code is different from the comment. Still, it's good information about why the code might once behaved as the comment indicates.

My programming style:
I comment all the functions, decision points, and logical blocks; no need to comment every single line. The important thing to comment is the purpose of the block. The code itself should explain the how the task gets done and comments indicate the intended purpose. It's quite tedious to go back and add comment afterward. It's much easier to write all the comments first then write the code. This extra step helps me to think clearly about the logic of the function and plan out the work that needs to be done. When I write the comment, I'm not concerned about the variable names, structure, efficiency, optimization, memory usage, variable type, or million of little things that a programmer thinks about when coding. The comments focus purely on correctness of the logic.

No comments: