I just found myself writing the following comment in some (archaic Visual Basic 6.0) code I was writing:

If WindowState <> 1 Then
'The form's not minimized, so we can resize it safely
'...
End if

I'm not sure why I subconsciously use "we" in my comments. I suspect it's because I imagine someone stepping through the code, as if they were actually "doing" all of the commands on each line, rather than just watching them happen. With this mindset, I could have used I can resize it, since I'm the one "doing" it currently, or you can resize it, as if I were speaking to whomever is "doing" it in the future, but since both of those of these cases will most likely happen, I use "we" as if I'm leading someone else through my code.

I can simply rewrite it as it can be resized and avoid the issue, but it's sparked my curiosity: is it common to use first person like this in comments, or is it considered distracting and/or unprofessional?

I didn't downvote you but I could guess that they didn't like the title question as answers to it could easily be short, chatty, and overly given to unbacked opinion. Rewording that to be more like your final question might help.
–
DKnightJul 8 '11 at 20:05

51

I like the 'we'. Its friendly and inclusive in a wholesome, folksy kind of way.
–
JeremyJul 8 '11 at 20:40

23

I think I'm going to start commenting all the bug fixes I work on in third person omniscient, should make me popular around the office..."Little did John know that his poorly crafted addition would always skip this code, leaving users perplexed by the perpetually empty display field..."
–
DKnightJul 8 '11 at 20:49

1

I've seen a tendency where I work to use impersonal forms in comments (in Italian) like /*Il form non è ridotto a icona, si può ridimensionarlo tranquillamente*/ that is /*The form is not minimized, it can be resized safely*/ . Usually also software's user interfaces are written in a impersonal form.
–
Federico CullocaJul 8 '11 at 21:47

4

It;s all I can do to make sure my comments don't haev goofy typos. Now I need to worry about whether or not passive voice should be used? Next I'll have to make sure I don't dangle any prepositions - I imagine that is something my colleagues may not put up with. And I suppose I won't be allowed to ever use a split infinitive. Sentence fragments?
–
Michael BurrJul 9 '11 at 4:24

17 Answers
17

Comments should be written for human beings to understand. When human beings communicate, we typically use "I", "we", "you", etc.

When someone is trying to understand some code, there are two or more actors: the person reading it, and the original author of the code. Saying "we" is fine. Unless by 'professional', you mean 'robot-like'.

+1 and an amplification: contrariwise, passive-voice constructions like "it can be resized" are rejected in writing generally as we find them difficult to understand. If you use passive-voice you force your reader to invent and remember a subject for the sentence.
–
mswJul 9 '11 at 10:32

1

@msw: shouldn't that be 'we reject passive-voice constructions like "it can be resized"...' then?
–
tdammersJul 9 '11 at 19:44

1

@msw, in Russian, for example, passive voice constructs are more common and are understood more easily due to some cultural differences. (And no, I did not write that sentence in passive voice on purpose!)
–
Pavel ShvedJul 18 '11 at 14:29

Typically, I write comments in the manner suggested by The Mouth of a Cow. I also always write documentation-generating comments (Doxygen, JavaDoc) in this manner.

However, many often neglect the use of version control to identify who wrote/touched lines in source files. There are times when saying "I" is appropriate, especially when it's fairly easy to track the "I" back to the person who wrote the code. If you, as an individual, made a decision, I recommend using "I" (along with version control) to identify and track decisions in-line with the code.

I would suggest staying away from using 'I' because it automatically assumes all responsibility for the code. If other people are reading it, it would look bad because it's meant to be a team effort in this case. I'm indifferent about using 'we'. It may, however, come across as including other readers ungenuinely.

My vote still goes for brevity and conciseness. If the message can be conveyed in a less-verbose manner, why choose anything else? So, regarding this example, I would write:

"If the message can be conveyed in a less-verbose manner, why choose anything else?" As someone who has had to bang his head up against the wall trying to implement someone's poorly documented libraries --open source libs are notorious for this-- I say I would much rather have too many comments than too little. I think I agree with you in though if you mean use good sentences with correct punctuation that makes sense.
–
Jonathan HensonJul 8 '11 at 21:36

3

+1 for not assuming all responsibility in a team setting. And while I agree about trying to avoid verbose comments, sometimes the passive tense can be even harder to read (as jkj pointed out) and no less verbose, and I prefer to eschew obfuscation. =]
–
dlras2Jul 9 '11 at 2:44

2

@Jonathan Henson: Many comments are good, but only if they contain a lot of useful information. If the same amount of information can be expressed in two equivalent ways, the shorter one is better.
–
tdammersJul 9 '11 at 19:46

Why? Not because of the possessive nature of I, but because when people talk in any other perspective, they tend to use too many words or make sentences too complex, and get lost in trying to explain things. The first person tends to always be easiest to read.

It doesn't matter. Chances of some programmer actually going through your code are usually zero unless you are writing special things like Gmail APIs. So most comments will be for your own use and you can write in whatever way you like. Even in Klingon.

In a work setting, the chances of another programmer reading my code are actually pretty high. Why do you think otherwise?
–
Anna Lear♦Jul 9 '11 at 1:14

1

-1 This isn't the case in most programming environments. In fact, it's probably not even the case in yours - what about whoever takes over your code after you leave the company?
–
doppelgreenerJul 18 '11 at 13:14

Maybe we is referring to the little guys inside the program making the magic happen? :)

English language passive voice is hard to use and sounds bad. People like to use person forms (I, you, we, one).

Example:

(You/we/one must) use a delegate to pass window resize events to parent

A delegate has to be used for passing window resize events to parent

Another example (note that you can often omit the person forms in comments):

(We) caught an exception. (We'll be) showing an error dialog.

An exception was caught and an error dialog will be shown.

PS. Replacing passive with "you" is so common in the English language that it has started to leak into other languages too. It sounds extremely funny in, for example, Finnish where the second person singular form exists (like the English "thou").

You added this comment because the code wasn't clear enough. I generally find expressing intent through well defined methods avoids the use of comments. For instance, that line of could could have been moved to a method named CanThisFormBeResized.

A well named method, however small, beats a comment, because it's easy for comments and code to become out of sync.

So, if most comments can be expressed in code, that leaves very few reasons for comments

If your comment is your opinion, then start with "I"

If you think your comment should be a shared opinion (e.g. a best practice), then start with "we"

If your comment is directed at some dodgy code written by a half-wit, then scrap the comment and walk over and punch them confusing code from a colleague, then address this face-to-face with them.

Sorry, but I'm not really a fan of this style at all. Especially since this code is used once, in one place, and it's already the only thing in the resize method. I'd prefer a short, well-worded comment to added complexity through refactoring, especially when working with the VB6 debugger. As an aside, CanThisFormBeResized should probably be ThisFormCanBeResized if it's going to be used like If ThisFormCanBeResized Then.
–
dlras2Jul 10 '11 at 15:46

@Dan, what if someone else comes along later: why make them search around and re-figure out the logic to determine if a window can be minimised? They might not even spot your little line of code with a comment and add their own. Now you've got 2 places that need changing if the logic changes and 2 places where the comments could become out of sync with the code. Why is a well named 1 line method (that doesn't change state) added complexity? It's the simplest and one of the cleanest refactorings there is.
–
Steve DunnAug 26 '11 at 6:42

If you're talking about the execution of the programme, it's not 'we', 'you' or 'I'. Anthropomorphism may be so widespread as to be unnoticeable but it's a dangerous habit (PDF Warning. Dijkstra Warning.):

I think anthropomorphism is worst of
all. I have now seen programs "trying
to do things", "wanting to do things",
"believing things to be true",
"knowing things" etc. Don't be so
naive as to believe that this
use of language is harmless. It
invites the programmer to identify
himself with the execution of the
program and almost forces upon him
the use of operational semantics.

Am I the only one who writes "we" and thinks "me and the computer" (or "my team and the computer")? "We" are going to handle the request the outside gave us, that means "we" need to read the request, open some windows, do some calculations, based on "our" business requirements. This also helps to see the code as a part of your side, not the enemy :-)

-1 because: there isn't a correct way, I find your summary of I/You/We a bit out of touch and I don't understand the last part. Aside: When I say "we" in my comments, I'm not trying to talk like a king - I'm talking to you, the guy reading my code, and walking you through my thoughts side-by-side.
–
doppelgreenerJul 9 '11 at 1:02

I don't think either first person or the "royal we" seem unprofessional, or distracting. I do think that we should make an effort to write English-language comments in E-Prime, the subset of English that does not possess the "to be" verb.

If you over-use "to be" in comments you get confusing statements like:

// X is 10
// X is the user data of the newly-authenticated user
// X is a BigInt

Well, maybe not all at once, but the is-of-equality can really make comments unclear.

I think that writing requirements in E-Prime helps make those requirements clearer, as the writer must indicate an actor along with the action.

Comments should tell you why something is being done, not what is being done. If what is being done is not obvious from the code, fix the code, don't just add a comment. First-person, second-person, etc. do not matter, what matters is communicating necessary information.

If you must narrate the code, prefer imperatives, e.g.

'ensure that the window is not minimized
If WindowState <> 1 Then
'resize the window
'...
End if

+1 for preferring imperative, I hadn't thought of that. Also, yes, I shouldn't have used the bare 1. I'm usually pretty good about that... Leave it to me to post one of the few times it slipped my mind on the internet.
–
dlras2Jul 9 '11 at 2:35

I personally do not feel that "one" is dated. Yes, it's in less common use, because it's not something that one uses from time to time. However, there's little to zero chance that using "one" in that sense of a comment is going to be unreadable or otherwise detract from usability.
–
Billy ONealJul 9 '11 at 3:57