General - Preferred commenting objective

Question

Hello,

I highly like to comment my code for my own reference, and also since i keep (most) of my projects open-source.

I current comment as if I'm the narrator:

// Check if y is higher than x.

Should i comment as if im talking to a group of people?:

// Now we check if y is higher than x.

This isn't much of a question, i just want to get people's commenting preferences

Answer 1

I prefer commenting in the third person so it sounds more like a programmatic story. This has proven useful in the past when debugging not only my own code but someone else's. To each his own.... Key part in your example is not to "repeat the code"!

For example:

count = count + 1 // Add to the count <- BAD

This presentation here describes how to write good comments.

Or, you can review this blog entry Make the Software Shine: How to Write Good Comments.

Answer 2

I tend to avoid any reference to people.

// This hack was added for backwards compatibility.
// This was done to avoid side effects.

Answer 3

I usually comment in what is known as "first person plural", which simply means I use "we" as the pronoun. I'm not sure how I developed this habit, but I find it has an instructive quality to the reader. For example:

/* After this API call, we need to deconstruct the result array for 
 * the 'stat' parameter before we can activate the widget.
 * Otherwise, the widget will fail with no error output.
 */

I made that up, but when reading it, I get the sense that someone is instructing me as to why this code does what it does.

Answer 4

I really don't care how the comments are phrased, as long as they are commenting the right thing.

I don't need you to tell me that you're checking if x is greater than y, I need you to tell me why you're doing it.

"Check if we need to calculate the delay time required." is much better than "Check if x is greater than y".

Answer 5

G'day,

As Mark Byers says in his comment to the question, explain why you are doing it.

Have a look at the relevant section in Steve McConnell's "Code Complete 2". Too many comments serve to detract, especially when the are of the type "now add one to the counter".

Comments should only be there if it is necessary to highlight something in the code or to explain why you are doing something. Not just "adding to the noise".

HTH

cheers,

Answer 6

Maybe you should investigate 'literate programming' as a way of writing your code. That interleaves commentary with code, allowing for presentation of the code in a logical sequence.

Apart from the originals by Donald Knuth, you could look at 'C Interfaces and Implementations' by D Hanson.