Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
1  
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. –  DKnight Jul 8 '11 at 20:05
49  
I like the 'we'. Its friendly and inclusive in a wholesome, folksy kind of way. –  Jeremy Jul 8 '11 at 20:40
22  
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..." –  DKnight Jul 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 Culloca Jul 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 Burr Jul 9 '11 at 4:24

17 Answers 17

up vote 95 down vote accepted

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'.

share|improve this answer
2  
+1 as writing this way encourages you the writer to consider the potential reader and that can really help you see concepts that might need to be better expounded upon. –  Justin Ohms Jul 8 '11 at 22:13
58  
// we approve of this answer :) –  Jarrod Dixon Jul 9 '11 at 1:36
3  
+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. –  msw Jul 9 '11 at 10:32
1  
@msw: shouldn't that be 'we reject passive-voice constructions like "it can be resized"...' then? –  tdammers Jul 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 Shved Jul 18 '11 at 14:29

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:

'The form is not minimized so it can be resized safely.
share|improve this answer
4  
"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 Henson Jul 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. =] –  dlras2 Jul 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. –  tdammers Jul 9 '11 at 19:46

I take one of two approaches, usually just whatever sounds better.

In explaining things like requirements or justification, I go with "we" as you have there:

// We can't proceed unless the user has given us this information.

If I'm explaining the process, I tend to use an imperative (command) voice (correct me if that's the wrong term):

// Get the foo from bar and make sure it follows our required format.

The latter can get dangerously close to repeating the code, but there are uses. So it's not using I or we, but instead it actually implies "you".

share|improve this answer
9  
The latter has "our" in it, too. I find it interesting that people naturally write comments in first-person plural. –  Reid Jul 9 '11 at 1:52

I think it's just a variation on academic/technical writing style, which is often impersonal. Using the passive voice, using the "royal we" ("one" is so dated).

As a general rule, it is non-specific who will use it anyway - the comment is for maintainers benefit, not normally just for the original author.

That said, I use first person quite often in comments - to explain why I made particular decisions, and what I was thinking.

share|improve this answer
3  
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 ONeal Jul 9 '11 at 3:57

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

(And please don't use bare constants like "1" in the code)

share|improve this answer
3  
+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. –  dlras2 Jul 9 '11 at 2:35

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").

share|improve this answer

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.

share|improve this answer
2  
Dijkstra Warning! If only more things had one :( –  Tom Anderson Jul 10 '11 at 9:28

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.

share|improve this answer

The correct style for commenting is the third person impersonal; "The form's not minimized, so it can be can resized safely".

  • I is naive.
  • You is crass.
  • We is too formal (and royal).

Every sentence can be rephrased in this way (see above) and it is the only professional way to write.

share|improve this answer
10  
-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. –  Jonathan Hobbs Jul 9 '11 at 1:02

It depends on the comment.

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.

share|improve this answer

My good old father (mhrip) would ask: "Don't you have more important things to bother with?"

However, personally, I like the "we". And I also find myself wondering why I write we in up-stream documents, not even code, considering I'm the only employee in my company.

However, me myself and I agree that this way we feel less lonely :)

share|improve this answer

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 :-)

share|improve this answer

For short comments, I sometimes write in the second-person, as if I am instructing someone else, almost as a message directed to the next developer to read the comment. Such as

//You can get a session_id from SYSSession.getSessionID() if you need one

Longer comments (such as a long function header or several lines of algorithm description) I try to keep neutral, no first-person, second-person, or third-person.

share|improve this answer

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.
share|improve this answer
1  
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. –  dlras2 Jul 10 '11 at 15:46
1  
Thats preference. I take a private boolean method like function() { return this.windowState != 1 } over any comment. +1 from me –  keppla Jul 11 '11 at 15:56
1  
@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 Dunn Aug 26 '11 at 6:42

As a rule of thumb I would suggest use the first person, that is, I.

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.

share|improve this answer

Personally I would write (in C#):

if (WindowState != WindowState.Minimised)
{
     ResizeWindowSafely();
}

Or something along those lines, thus not needing the comments.

share|improve this answer

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.

share|improve this answer
8  
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? –  Jonathan Hobbs Jul 18 '11 at 13:14

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.