Are first person comments distracting and unprofessional?

Question

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?

Answer 1

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

Answer 2

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.

Answer 3

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

Answer 4

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.

Answer 5

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)

Answer 6

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

Answer 7

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.

Answer 8

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.

Answer 9

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.

Answer 10

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.

Answer 11

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

Answer 12

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

Answer 13

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.

Answer 14

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.

Answer 15

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.

Answer 16

Personally I would write (in C#):

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

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