--
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 |
--
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.
We, in the context of a comment, generally means "myself and you, gentle reader, as two people stepping through the code flow".
Really? Have you ever referred to data as "you"?
Have you ever seen a computer referred to as "you" in a comment?
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.
Not all pronouns need to be excised.
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".
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).
M-A