Which writing style do you use when commenting code?

Question

I'm really just curious, but if someone wants to make an argument that one is better than another - go for it!

These are comments for example of writing style only, not meant to be judged by their content!....

• First Person "I" comments:

  //i'm setting this to 1 because it breaks otherwise

• First Person "we" comments:

  //we need to set this to 1 - trust me

• 2nd Person:

  //you need to set this to 1 so it don't break

• 3rd Person:

  //this needs to be set to one

Answer 1

Here's a link from Microsoft, it's specifically aimed at coding standards / guidelines when targetting the .NET framework. But it might be useful.

http://msdn.microsoft.com/en-us/library/aa291593.aspx#vxconcodingtechniquesanchor2

And out of your choice of 4, I tend to use #4.

Answer 2

I mix all three as appropriate, which might not be best practice when composing prose.

Answer 3

I'll alternate between "I" and "we" depending on if it's wholly my fault, or a committee/peer programming decision.

Answer 4

"I", if it's a hack I'm embarrassed about.

"We", if I'm taking the reader through a confusing algorithm.

"You", if I'm explaining how to use an API.

Answer 5

I'll use 'I' if I'm explaining my own decision to use a certain logic or pattern. If it's a group project I'll usually sign that comment so people can come to me directly with questions.

Otherwise I'll use 3rd person.

Answer 6

I use 3rd person for all comments.

Answer 7

You never know if that code will be used for someone else, you can sell the code, you can published under any open source license, etc... So it is not good to see "I'm setting this..." or "We need to set this..." at least, "Please update the following variables:"

I always use the 3rd person and cause you are it, I always use

/*********************************************
**
** last edited by Bruno Alexandre, 14.Oct.08
** log info:
**  - 10.Oct.08 : Added send email when buggy
**
************************************************/

on the top of each code page (Classes, CSS, Javascript, etc)

and use to the code it self:

// check if user has already newsletter subscription

if ( !mySubscription.Contains( myUser ) )...

Answer 8

Third person, but please, please include an explanation. Needn't be lengthy or exhaustive, just why you're doing this, what will break if it's changed, something. No, I don't trust you, or I don't trust that the current circumstance will always require this hack. The associated bug might be fixed now, five years later. Or it might be easier to fix.

Answer 9

I either depersonalize my comments or use "we". "We" in the sense of walking though the algorithm with the reader.

Answer 10

I mostly use the imperative mode for one-liners ("Compute the foobar by applying the barfoo algorithm", "Refer to Foo and Bar 1967 for details), "We" for longer explanations that could be excerpts from a technical article.

Passive 3rd person is more traditional, but a lot of scientific journals prefer the more active "we" since it's more readable. It's also my favorite form, so that's the guideline I use in my documentation and comments.

Answer 11

//use imperative mode, few person/reader references if any
//comments generally annotate the code, rarely talk to the reader
//there is no reason to talk to the reader
//this is not a primer or a tutorial
//just record the information
//state the context
//note the exceptional cases
//justify the choices
//list just the facts
//save the prose for poetry and sci-fi
//some code is sci-fi, but hopefully not this

Answer 12

Mostly in passive voice, what is generally more important than who for me.

//This must be set to one for configuration
// This is yet to be implemented
// still to be evaluated for edge cases

etc.