Commenting Code

Commenting code is something that all programmers, especially the students and newbies, are constantly reminded to do.

But how do you best go about it, and more importantly, how do you know when to add comments? Steve C McConnell says a good place to start is with good code:

Good code is its own best documentation. As you're about to add a comment, ask yourself, 'How can I improve the code so that this comment isn't needed?' Improve the code and then document it to make it even clearer.

The worst code i've seen would not have been helped by adding comments. The code itself needed to be drastically changed.

Code which has a logical structure and meets the requirements of Obejct Orientated design can often be worked out. It is when the programmer him or herself does not know what the class is meant to be doing that problems arise.

So sort out the code and comments will naturally follow.