Take the 2-minute tour ×

Possible Duplicate:
How do you like your comments?


Edit 2: Where the above question asks for general thoughts on commenting code, I am more interested in ways to ensure that code and comments stay in step.

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 keeping comments and code in step.

Apart from an excellent technique for removing the necessity for writing comment's, this blog post by Jeff about commenting doesn't really cover keeping things in step.

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

share|improve this question
This is too subjective. –  bmargulies Apr 10 '10 at 22:11
About a zillion dupes, such as stackoverflow.com/questions/121945/… –  anon Apr 10 '10 at 22:13
@bmargulies How can a question that relates to the quality of the code you deliver be "subjective"? It's about getting tips for doing the best job you can do. –  Rob Wells Apr 10 '10 at 22:20
add comment

marked as duplicate by bmargulies, mjv, Jon Seigel, John Saunders, James McNellis Apr 11 '10 at 0:16


3 Answers

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.

share|improve this answer
add comment

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.

share|improve this answer
@Jason, I appreciate what you say but one of my big worries is that comments, as you've described, will not be updated along with the code and will be stale for some future release. –  Rob Wells Apr 10 '10 at 22:34
Commenting is part of writing good code. (Indeed, I often write many of the comments before I write the code, as they form a "micro design" that makes me think about the code I'm about to write). Your options are to stop commenting (so code quality drops significantly) or to use code reviews to ensure that good commenting standards are met. Most good software houses use the latter approach. Keeping coments up to date is easy, it's just a skill we all have to work omn. –  Jason Williams Apr 11 '10 at 8:40
add comment

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 :)

share|improve this answer
add comment
