Code Comments

What makes good code comments? Should they be terse or expansive? Should they be frequent or used sparingly? Opinions on these and other aspects of code commenting vary widely. My take is this ... to answer these questions, start with the objectives for code comments:

To assist in development: Comments aid in understand functionality being implemented in code. For example, they can be used as pseudo-code place holders for eventual real code.

To speed development and maintenance: Comments allow more rapid digestion of code sections. This is especially important when revisiting code not recently seen or code developed by others.

To clarify code: The function of a section of even well constructed code may not be evident. Comments can add that critical piece of missing information.

Given these objectives, here are some suggestions:

Comment appropriate groups of code: Sometimes a single line of code might need explanation. Or there might be a long section of code that repeats similar functionality and a single comment will suffice for the group. It's a judgment call.

Leave signposts for developers: Even if a section of code can be understood without a comment, how long will it take for you, or someone else, to understand it after time passes? Also, it's sometimes important to be able to understand the flow of a function or application without necessarily understanding all the details. Give yourself and others a break, make understanding as easy as possible. Most code is not a programming quiz.

Clean up comments: Keep them up to date and free of extraneous information. Remove temporary words used during development. Make them understandable. After all, that's their purpose in life.

Add comments while coding: It's tempting to think you can go back later and add a comment to some code that looks perfectly clear to you as you write it. Don't do it. Leverage the knowledge you have in that temporary cache in your brain.

Use a fairly uniform comment style: You don't have to be perfectly uniform, but it's a good idea to used some consistency within an application. It helps with understanding and looks more professional. 

Add value to the code being commented: Don't just repeat what the code obviously tells you. Make the comment compliment and add value to the code.