General - preferred commenting goal

Question

I really like to comment on my code for my own link, and also because I keep (most) of my open source projects.

It seems to me that I'm a storyteller:

// Check if y is higher than x. 

Do I have to comment as if I'm talking to a group of people?

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

This is not a big question, I just want people to comment on the settings

Answer 1

I really don't care how the comments are formulated if they comment on the right thing.

I don’t need you to tell me that you are checking if x is greater than y, I need you to tell me why you are doing this.

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

Answer 2

I prefer to comment in the third person, so it sounds more like a program story. This has proven useful in the past when debugging not only my own code, but also another. To each his own. The key part in your example is not "repeating the code"!

For instance:

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

This presentation describes how to write good comments .

Or you can view this blog post Make Shine Software: How to Write Good Comments .

Answer 3

I try to avoid references to people.

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

Answer 4

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

 /* 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 did this, but while reading it, I realized that someone is instructing me on why this code does what it does.

Answer 5

G'day

As Mark Byers notes in his commentary on the question, explain why you are doing this.

Look at the relevant section in Steve McConnell's article " Code Complete 2 ". Too many comments serve to reduce, especially when they are of type “now add one to the counter”.

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

NTN

amuses

Answer 6

Perhaps you should explore literate programming as a way to write code. This alternates the comment with the code, allowing the code to be presented in a logical sequence.

Besides the originals of Donald Knuth, you can look at the "C-Interfaces and Implementations" by D Hanson.