2nd or 3rd person comments?

Question

Do you write comments in 2nd or 3rd person?

// go somewhere and do something (2nd person comment)

or

// goes somewhere and does something (3rd person comment) 

Answer 1

Definitely 3rd person style.

Answer 2

I often tend to speak doctor style:

// Now we take $x and check whether it's valid for this pass

Answer 3

One helpful tip: try to keep each comment as self-contained as possible. For example, this form:

// First, mumble the frabbitz.

blah blah

// Second, foobar the quux

blah blah

this is a nice narrative, but makes it harder to edit the code, because the "First" and "Second" parts may become incorrect. In the end, they don't add that much to the comments, but make them interrelated in a fragile way.

Answer 4

I sometimes speak in 1st person, like this

/*
Usage:  
set_position(0.5, 0.5);  // im in the center
set_position(0.0, 1.0);  // im in the lower,left corner
*/

Answer 5

It may depend on how many people are editing the code and for what purpose. In my own code (which is nevertheless for public view) I may feel free to add some personal comments, perhaps using 'I'. In a communal project the comments should aim at a communal style and 'I' may be out of place.

Note that comments are fragile and many modern authorities (e.g. Clean Code) suggest that functions and fields should carry meaningful names. But, of course, there are many places where explanatory comments are still vital.

Answer 6

My view is that you should just use whatever style you feel most comfortable with.

Embedded comments are intended to be read by you and other developers trying to understand the implementation details of your code. So long as they are clear and intelligible, it does matter if they style is a bit unusual, the grammar is a bit poor, or there are a few spelling errors. The folks who are reading it should be beyond caring about such things.

Comments that are extracted to form API documentation deserve a bit more attention to the niceties of style, grammar and spelling. But even here accuracy and completeness are far more important.