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?

  • 1
    Comments for the downvote? This is my first Programmers.SE question, and I'm still trying to figure out exactly what makes a good P.SE question vs. a good SO question.
    – dlras2
    Commented Jul 8, 2011 at 19:54
  • 2
    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
    Commented Jul 8, 2011 at 20:05
  • 57
    I like the 'we'. Its friendly and inclusive in a wholesome, folksy kind of way.
    – Jeremy
    Commented Jul 8, 2011 at 20:40
  • 26
    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
    Commented Jul 8, 2011 at 20:49
  • 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? Commented Jul 9, 2011 at 4:24

16 Answers 16


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

  • 4
    +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. Commented Jul 8, 2011 at 22:13
  • 68
    // we approve of this answer :) Commented Jul 9, 2011 at 1:36
  • 4
    +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
    Commented Jul 9, 2011 at 10:32
  • 1
    @msw: shouldn't that be 'we reject passive-voice constructions like "it can be resized"...' then?
    – tdammers
    Commented Jul 9, 2011 at 19:44
  • 2
    @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!)
    – P Shved
    Commented Jul 18, 2011 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.
  • 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. Commented Jul 8, 2011 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
    Commented Jul 9, 2011 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
    Commented Jul 9, 2011 at 19:46
  • My advice is to avoid using the passive voice. It is more difficult to understand, especially for non-native English speakers. Commented Jul 22, 2012 at 8:34

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

  • This is exactly my style too. Both ways you describe have their place.
    – zourtney
    Commented Jul 8, 2011 at 21:37
  • 11
    The latter has "our" in it, too. I find it interesting that people naturally write comments in first-person plural.
    – Reid
    Commented Jul 9, 2011 at 1:52
  • @Reid wow yeah that was just instinct, I didn't even notice. But it could just have easily had said "the".
    – Tesserex
    Commented Jul 10, 2011 at 13:40

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.

  • 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. Commented Jul 9, 2011 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)

  • 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
    Commented Jul 9, 2011 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).


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

  • I think linguistically this is not correct. The first is the imperative, it doesn't have a subject. "Please close the door." While it roughly means the same as "please, can you close the door?" it is a distinct grammatical form, not an abbreviation. In the second example, you could just as well say "(It has) caught an exception. (It will be) showing an error dialog."
    – Inca
    Commented Jul 10, 2011 at 9:50

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.

  • 2
    Dijkstra Warning! If only more things had one :( Commented Jul 10, 2011 at 9:28
  • I don't think writing comments in the first-person plural is an anthropomorphism. I think it implies, "Now we instruct the computer to...", as if the programmer writing the comment is leading the reader through his code.
    – user249895
    Commented Oct 14, 2016 at 9:11

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.

  • Interesting notion; how would one express the notions of "X should be at least 5" or "Y must be no greater than 23"?
    – supercat
    Commented Apr 10, 2014 at 20:27
  • @supercat - "The value of X must have magnitude of 5 or greater". "The value of Y must not exceed 23". Equality, logical or arithmetic, should not use the "to be" verb either. "X must contain 5", or "X evaluates to 5" or "X has the value 5" or somesuch. If you come across a particularly unclear comment, look for "to be" verbs. I bet that unclear comment uses noting but "to be" verbs. Also note that I wrote the answer above in E-Prime. Commented Apr 10, 2014 at 20:37
  • The second is fine; the first not so much, since -6 has a magnitude of 5 or greater.
    – supercat
    Commented Apr 10, 2014 at 20:40
  • @supercat - very well. "X must have a signed integer value of 5 or greater". In the US, we would call your "magnitude" "absolute value", which reinforces my point of describing the value of a variable, not the variable-as-value, which arises from the is-of-equality. Commented Apr 10, 2014 at 23:07

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.

  • 12
    -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. Commented Jul 9, 2011 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.

  • +1 for Doxygen and JavaDoc. I agree that documentation is distinct from comments, (though some comments generate documentation,) and I do my best to keep such documentation a step more formal than my commenting.
    – dlras2
    Commented Jul 9, 2011 at 2:51

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


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


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.

  • English passive rarely sounds good: "A session_id can be gotten from SYSSession.getSessionID() if one is needed"
    – jkj
    Commented Jul 8, 2011 at 23:26

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.
  • 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
    Commented Jul 10, 2011 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
    Commented Jul 11, 2011 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
    Commented Aug 26, 2011 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.


Personally I would write (in C#):

if (WindowState != WindowState.Minimised)

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

  • ResizeWindowSafely would imply it can be called if you don't know whether to resize or not, and thus would need to include if (WindowState != WindowState.Minimised) itself.
    – dlras2
    Commented Jul 14, 2011 at 12:26

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

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