Do you have any tips for comments to keep them in step with the code?

Question

Possible Duplicate:
How do you like your comments?

G'day,

I've read both of Steve McConnell's excellent Code Complete books "Code Complete" and "Code Complete 2" and was wondering if people have any other suggestions for commenting code.

My commenting mantra could be summed up by the basic idea of expressing "what the code below cannot say".

While enjoying this interesting blog post by Jeff about commenting I was still left wondering "When coding, when do you feel a comment is required?"

Edit: Oops. Seems to be a duplicate of this question http://stackoverflow.com/questions/121945/how-do-you-like-your-comments so sorry for the noise. Thanks to my, seemingly, SO shadow for pointing it out - wouldn't have thought I was that interesting.

Now off to read the original post and see if it is relevant.

Edit: I meant to emphasise the best appraoch to ensure that your comments will stay in step with the code. Maybe expressing an intent rather than the mechansim for instance.

Answer 1

Just comment things that you might not find too intuitive to yourself, if you come and see your code after 6 months!

This way, you are doing a favor to your future self (generally you will be the one who will visit the older parts of code later) and also to others who latter might be maintaining your code :)

Answer 2

As you say, comments should express what isn't already obvious from the code (the reason for the code being as it is, the approaches that were tried and found to have flaws that led to the code being the way it is now, etc)

But in a more general sense, think of code as being logically grouped into related chunks. Namespaces, Classes, Methods, Blocks, Lines. These chunks form a hierarchical overview of the application. So by commenting the blocks and giving an overview of what they do, you can summarise the code and make it quick and easy for someone else to find the bit that is relevant to them, understand it, and then use or modify it effectively and with minimum risk of failure.

So explaining that File.Open opens a file is of no use.

But explaining that a block of 10 lines of code will locate, open, read, and store the preferences for your application, you save the reader having to actually read and decode the full text. In a few words they can understand the full purpose of the code, and know whether or not it is something they need to delve deeper into. Or if they wish to call the code, they will understand what it does and how to use it - again, without needing to actually delve into the finer details of how it achieves its behaviour.

So, a comment is required at the beginning of any important chunk of code (at any/all of the levels described above) where a summary will save the reader having to read the code to understand reasonably well what it does. And in any place where you need to annotate the code to explain how or why it does what it does.

Remember that your comment is describing code to someone who has never seen that code before. Or to yourself when you revisit it in 6 months. A few well chosen words can save hours of work trying to decode a full understanding of some code.

Answer 3

When you find yourself wanting to include a comment, ask yourself why that commented piece is not in its own method with its own method name... that way you comment the code via the method name and break it down into smaller steps to make it more lucid.