Pronouns in comments considered harmful?

[Drew Wilson]

I keep sporadically seeing reviewers dinging people for what seem to be fairly innocuous use of pronouns in their comments.

For example:

"/* Increase the width if you want to display more data in this div */".

Or

"// Now that we have an OAuth token, we can safely issue a call to the server"

Generally the rationale given has been either "It's against the style guide" (as far as I can tell, it isn't) or "I personally don't mind, but some people object to it" (who are these mysterious people?)

I find that my natural writing voice involves pronouns, and avoiding them in my comments, while possible, is annoying me. Clearly, ambiguous comments should be flagged in a review:

"// It will not be properly initialized if we don't send this notification now"

...but I don't think that should translate into a blanket prohibition against pronouns. So, anyone want to lay out the argument in favor of banning pronouns? Otherwise, this will be the thread I link to when in the future I ignore people's review feedback on the subject :)

-atw

[Pam Greene]

The reviewer replying here thinks pronouns are fine, and often the most understandable way to explain something.

(Although

"/* Increase the width if you want to display more data in this div */".

could easily be made more succinct:

"/* Increase the width to display more data in this div */".

)

- Pam

--
Chromium Developers mailing list: chromi...@chromium.org
View archives, change email options, or unsubscribe:
http://groups.google.com/a/chromium.org/group/chromium-dev

-- 

Google Germany GmbH Dienerstr. 12 80331 München

AG Hamburg, HRB 86891  Sitz der Gesellschaft: Hamburg

Geschäftsführer: Graham Law, Katherine Stephens

Tax ID: 48/725/00206  VAT ID: DE813741370

[Mark Mentovai]

Who are “we?” Is it the team? Some subteam? Are you personifying the code itself? Are you talking about a class or an object or a process or a thread or a data center? “We” don’t know. Who are “you?” Is it the user or the engineer who’s reading the comment or the data that the attached code operates on or some computer? These are linguistic crutches that distract from your comment’s content while making it less concise. Comments should be direct and clear.

"/* Increase the width if you want to display more data in this div */".

/* Increase the width to display more data in this div */

"// Now that we have an OAuth token, we can safely issue a call to the server"

// With an OAuth token, it's now safe to issue a call to the server

Like the code itself, comments are written to be read by other engineers. You’re not writing an e-mail which is unambiguously from one individual to a defined audience. You’re not giving a talk or having a phone call or signing a letter. You don’t know who’s going to need to maintain or modify your code in the future, or how many people might wind up filling those roles. Google and Chrome tradition holds code to a high standard of clarity, and as an extension of the code, comments should adhere to the same principles. Over-designed classes that implement more features than will actually be used are discouraged. So are overly complex comments that use more words than they need and less direct language to convey a point.

Mark

(I’m not really that mysterious.)

--

[Drew Wilson]

On Wed, Nov 14, 2012 at 4:35 PM, Mark Mentovai <ma...@chromium.org> wrote:

Who are “we?” Is it the team?

We, in the context of a comment, generally means "myself and you, gentle reader, as two people stepping through the code flow". It could, I suppose, mean "the chrome team", as in "We take our user's privacy very seriously".

 

Some subteam? Are you personifying the code itself? Are you talking about a class or an object or a process or a thread or a data center? “We” don’t know. Who are “you?” Is it the user or the engineer who’s reading the comment or the data that the attached code operates on or some computer?

Really? Have you ever referred to data as "you"? Have you ever seen a computer referred to as "you" in a comment? "You", in written communication means "you, the reader", except in very specific literary forms such as the open letter.

 

These are linguistic crutches that distract from your comment’s content while making it less concise. Comments should be direct and clear.

"/* Increase the width if you want to display more data in this div */".

/* Increase the width to display more data in this div */

"// Now that we have an OAuth token, we can safely issue a call to the server"

// With an OAuth token, it's now safe to issue a call to the server

Neither of those two comments are any clearer than my original made up examples, IMO. Certainly not a clear enough improvement to flag in a review.

 

Like the code itself, comments are written to be read by other engineers. You’re not writing an e-mail which is unambiguously from one individual to a defined audience. You’re not giving a talk or having a phone call or signing a letter. You don’t know who’s going to need to maintain or modify your code in the future, or how many people might wind up filling those roles. Google and Chrome tradition holds code to a high standard of clarity, and as an extension of the code, comments should adhere to the same principles. Over-designed classes that implement more features than will actually be used are discouraged. So are overly complex comments that use more words than they need and less direct language to convey a point.

So, I'm all for suggestions on how to improve specific comments. If a reviewer would like to suggest clearer wording in a review, I'm all for that. But I would disagree that the use of pronouns is inherently unclear *by their very presence*, which seems to be what you're implying.

For me, avoiding pronouns falls into the same general category as "order your functions in a .cc file so they match the order in the .h file" - it's something some people feel really strongly about (code quality!), so if you're updating a file that adheres to this philosophy you should maintain the ordering, but a reviewer shouldn't try to impose their personal preference on code they personally do not own because it's not part of the style guide.

[Ben Hayden]

The argument against pronouns that I've always heard and support is that they are ambiguous. Do they refer to the surrounding method or class, another method or class, one of the many mechanisms or concepts near the comment, a related test, the author, the maintainer, the maintainer's team, the whole chrome team, English-speaking users, users everywhere?

Technical writing is not casual young adult fiction, as much as I often wish it was.

The goal of technical writing is to specify the subject clearly, not appease reviewers or your own sense of  whether there should probably be some sort of comment here. I'll be the first to admit that I am often not up to the task of adequately specifying non-obvious aspects of code, but ambiguous pronouns almost never make that task any easier.

That said, pronouns are not the highest priority problem in comments by far. It's entirely possible to specify something clearly despite a stray pronoun, and it's possible to contort an otherwise good comment in the pursuit of eradicating pronouns. If all reviewers agree that a particular pronoun clearly refers to a specific previously-mentioned thing, then it's probably fine.

In general, I suggest asking reviewers to help draft and revise comments. What's clear to one is often unclear to another.

[Mark Mentovai]

Drew Wilson wrote:

We, in the context of a comment, generally means "myself and you, gentle reader, as two people stepping through the code flow".

How is a comment any more clear by involving the two of you?

Really? Have you ever referred to data as "you"?

I had no idea what to make of your div example. I reasonably thought that the code that comment was attached to was operating on some HTML, which could easily be external data. Oh, is that not what you meant?

Have you ever seen a computer referred to as "you" in a comment?

“// You need more than 1GB to benefit from the fast path”

 

So, I'm all for suggestions on how to improve specific comments. If a reviewer would like to suggest clearer wording in a review, I'm all for that. But I would disagree that the use of pronouns is inherently unclear *by their very presence*, which seems to be what you're implying.

If you started a sentence with “so” like that, I’d flag it in a review too.

Not all pronouns need to be excised. Excessive and gratuitous pronoun use is a marker that a comment could be improved. If a reviewer asks you to improve a comment, you should improve it. Who’s served by being obstinate? If you can’t improve it but your reviewer has a suggestion, take it. This isn’t really about pronouns at all, it’s about writing clear, concise, effective, understandable, and unambiguous code and comments.

For me, avoiding pronouns falls into the same general category as "order your functions in a .cc file so they match the order in the .h file" - it's something some people feel really strongly about (code quality!), so if you're updating a file that adheres to this philosophy you should maintain the ordering, but a reviewer shouldn't try to impose their personal preference on code they personally do not own because it's not part of the style guide.

Clarity is pretty much the fundamental basis of the style guide, and I’m assuming that you’ve asked someone for review because they have some sort of ownership claim over the code in question.

[Jói Sigurðsson]

My 2 cents:  I support Drew's position in general.  In my opinion, the use of pronouns in comments doesn't make a big enough difference that it should be outlawed in the style guide.

As a general rule, I think that if some rule is not in the style guide, reviewers should not be forcing patch authors to adhere to that rule.

There are several exceptions to that general rule, e.g. if there is an actual problem with clarity or correctness, or if the change is in violation of the local style (as dictated by OWNERS, or as witnessed by looking at the style of surrounding code).

I believe the style guide exists not just to establish our rules, but also to set the bar for what is important enough to care about.  In general, authors and reviewers shouldn't have to waste time going back and forth on things that have been deemed unimportant enough not to be in the style guide.  Such back-and-forth is unproductive for us as a team and frustrating for both parties.  My suggestion is therefore for this thread to end with a conclusion on whether or not a rule on the use of pronouns in comments belongs in the style guide, and whichever way the decision falls, to not revisit the discussion any time soon.

Cheers,

Jói

[Drew Wilson]

On Wed, Nov 14, 2012 at 5:14 PM, Mark Mentovai <ma...@chromium.org> wrote:

Not all pronouns need to be excised. 

Thank you, agreed :)

As before, I will continue to welcome any and all feedback on how to improve the wording of comments from my reviewers. I love getting feedback like "it would be clearer if you said X instead" or "It's not clear what object you're referring to here" - I just object to feedback that amounts to "you aren't supposed to use pronouns".

[Peter Kasting]

On Wed, Nov 14, 2012 at 8:27 AM, Drew Wilson <atwi...@chromium.org> wrote:

As before, I will continue to welcome any and all feedback on how to improve the wording of comments from my reviewers. I love getting feedback like "it would be clearer if you said X instead" or "It's not clear what object you're referring to here" - I just object to feedback that amounts to "you aren't supposed to use pronouns".

I support this position.

If a reviewer says "don't use pronouns" with no other context for why they decrease clarity, the reviewer's feedback is itself unclear.  Much better to be specific.

I do think there is a takeaway from this thread that, while pronouns are not banned, using one should prompt you to at least think about whether there's any way to word the comment more clearly, concisely, and directly.

There is also a more subtle takeaway that reviewers should be reading the comments and not just the code, and striving for maximum clarity there.  The reviewer is generally in a better position to judge clarity here since he hasn't just had his nose in the change for a while like the author has.  It is not only acceptable but encouraged to nitpick grammar, mechanics, etc. in comments.

PK 

[Silvia Pfeiffer]

On Thu, Nov 15, 2012 at 2:35 AM, Mark Mentovai <ma...@chromium.org> wrote:

Who are “we?” Is it the team? Some subteam? Are you personifying the code itself? Are you talking about a class or an object or a process or a thread or a data center? “We” don’t know. Who are “you?” Is it the user or the engineer who’s reading the comment or the data that the attached code operates on or some computer? These are linguistic crutches that distract from your comment’s content while making it less concise. Comments should be direct and clear.

"/* Increase the width if you want to display more data in this div */".

/* Increase the width to display more data in this div */

"// Now that we have an OAuth token, we can safely issue a call to the server"

// With an OAuth token, it's now safe to issue a call to the server

FWIW: to me the neutralised comments are clearer and easier to understand. I always welcome reviewers giving me feedback on how to improve my comments (in particular as a non-native speaker). It would be helpful to have some recommendations on the style of comment writing in the style guide - it would help beginners to write better comments. However, I would not make them requirements, but just recommendations, so reviewers can apply their own judgement.

Silvia.

[Marc-Antoine Ruel]

2012/11/14 Silvia Pfeiffer <silv...@chromium.org>

FWIW: to me the neutralised comments are clearer and easier to understand. I always welcome reviewers giving me feedback on how to improve my comments (in particular as a non-native speaker). 

I'd like to emphasize that point. A fair number are non-native speakers so using ~6th grade level for the comments do help.

M-A

[Mattias Nissler]

If we do accept that there are non-native speakers which may not be English language experts, I think there's another implication: If there's a precise and clear way of stating something using a pronoun, we shouldn't force non-native speakers to spend significant time on figuring out how to say the same thing while avoiding pronouns.

 

M-A