Chromium Code Reviews
|
|
Chromium Code Reviews
Issue
2778663002:
Add documentation on keeping code gender neutral. (Closed)
DescriptionAdd documentation on keeping code gender neutral.
This adds some documentation but doesn't yet link to it from anywhere.
BUG=None
Review-Url: https://codereview.chromium.org/2778663002
Cr-Commit-Position: refs/heads/master@{#460945}
Committed: https://chromium.googlesource.com/chromium/src/+/f6cc2ca5e909933d7cf891f4cece6a9af146655b
Patch Set 1 #
Total comments: 36
Patch Set 2 : Feedback #
Total comments: 4
Patch Set 3 : Moar Feedback #Messages
Total messages: 23 (10 generated)
benwells@chromium.org changed reviewers: + mgiuca@chromium.org
This is the .md version of https://docs.google.com/a/chromium.org/document/d/1LLycbnuktwZt38BY5CYF6ttAlE... which has been reviewed by the chrome-diversity list.
That's most of my thoughts but I haven't been super thorough yet. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... File styleguide/gender_neutral_code.md (right): https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:6: about the gender of a future reader, user, etc. __Example: “When the user logs nit: Do you think you should change the curly quotes and apostrophes to straight (so it's plain ASCII)? I'll leave this up to you. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:29: * “Guys” as a gender-neutral term. This has male associations and is easy to "..., which has male associations. Usually, it implies anthropomorphism of inanimate objects; it should be replaced with a more precise technical term. If it does refer to people, consider using "everyone", ..." https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:42: * For new code/comments, consider using just ‘A’, ‘B’ as names. 2-space indent. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:43: * Content of things like public-domain books. Quotations, and .. (Maybe a few of these can be combined?) https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:46: * Quotations from other non-chromium material, such as external documentation. Capital C Chromium. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:48: language. indent multi-line bullet points so all the text lines up on Column 3. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:52: * Try rewording things to not involve a pronoun at all. In many cases this makes * Avoid anthropomorphism of inanimate objects. Example: "Read an int and put him in the list." → "Read an int and put it in the list." https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:88: v8 repos. They are not run for other repos as there are too many false positives. nit: Word wrap. Also shouldn't line 88 be indented 2 spaces? https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:93: which can be found [here](https://goto.google.com/gender-neutral-code) (sorry, go/... (I think is the preferred way to share internal links publicly)
https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... File styleguide/gender_neutral_code.md (right): https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:41: * References to a specific fictional person ([Alice, Bob...](http://en.wikipedia.org/wiki/Alice_and_Bob)). nit: "Bob, ..." https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:50: How to change the remaining awkward intrusions of gender: "intrusions" is a weird word. How about "use of". https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:52: * Try rewording things to not involve a pronoun at all. In many cases this makes On 2017/03/27 06:58:39, Matt Giuca wrote: > * Avoid anthropomorphism of inanimate objects. Example: "Read an int and put him > in the list." → "Read an int and put it in the list." s/inanimate object/non-people (to use a term you used below) https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:57: reads reasonably. "if it reads reasonably".. hmm. I think this is subjective in the sense that lots of people (myself included) (purists if you will!) will tell you that it never reads reasonably; it is ungrammatical. And that is beside the point... we have made an institutional decision that gender-neutrality is more important than grammatical correctness, and therefore we should encourage use of singular they even when it is wrong. (Though you should first try to not involve a pronoun at all.) How about simply: "When referring to a person, try using [singular they]." You could even paraphrase my above paragraph in here if you like. And add the example from the bullet below that I'm going to tell you to delete: "When the user is done, he'll probably..." → "When the user is done, they'll probably..." https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:58: * Try making hypothetical people plural. “When the user is done he’ll I'm personally not a fan of this advice (I'd go with singular they here). It's just adding extra confusion to talk about multiple users (for example) when it's a single-user system. In general you shouldn't change the plurality of a sentence just to work around the awkwardness of singular they. Either embrace singular they (as you already recommend above), or do something else. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:60: → “When users complete this step, they probably…” When referring to a "When referring to a non-person" -- this feels like a separate bullet point. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:78: * To search for files contained gendered terms, use this command (or a variant s/contained/containing
https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... File styleguide/gender_neutral_code.md (right): https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:6: about the gender of a future reader, user, etc. __Example: “When the user logs On 2017/03/27 06:58:39, Matt Giuca wrote: > nit: Do you think you should change the curly quotes and apostrophes to straight > (so it's plain ASCII)? I'll leave this up to you. Done. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:29: * “Guys” as a gender-neutral term. This has male associations and is easy to On 2017/03/27 06:58:40, Matt Giuca wrote: > "..., which has male associations. Usually, it implies anthropomorphism of > inanimate objects; it should be replaced with a more precise technical term. If > it does refer to people, consider using "everyone", ..." Done. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:41: * References to a specific fictional person ([Alice, Bob...](http://en.wikipedia.org/wiki/Alice_and_Bob)). On 2017/03/27 23:42:06, Matt Giuca wrote: > nit: "Bob, ..." Done. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:42: * For new code/comments, consider using just ‘A’, ‘B’ as names. On 2017/03/27 06:58:40, Matt Giuca wrote: > 2-space indent. Done, let's see if it is recognized as an indent... https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:43: * Content of things like public-domain books. On 2017/03/27 06:58:40, Matt Giuca wrote: > Quotations, and .. > > (Maybe a few of these can be combined?) Combined this and the quotations one. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:46: * Quotations from other non-chromium material, such as external documentation. On 2017/03/27 06:58:39, Matt Giuca wrote: > Capital C Chromium. Removed this line. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:48: language. On 2017/03/27 06:58:40, Matt Giuca wrote: > indent multi-line bullet points so all the text lines up on Column 3. Why? It seems to work as is (when using the markdown command line utility). https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:50: How to change the remaining awkward intrusions of gender: On 2017/03/27 23:42:06, Matt Giuca wrote: > "intrusions" is a weird word. How about "use of". I think 'intrusions' conveys the right meaning here. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:52: * Try rewording things to not involve a pronoun at all. In many cases this makes On 2017/03/27 23:42:06, Matt Giuca wrote: > On 2017/03/27 06:58:39, Matt Giuca wrote: > > * Avoid anthropomorphism of inanimate objects. Example: "Read an int and put > him > > in the list." → "Read an int and put it in the list." > > s/inanimate object/non-people (to use a term you used below) are you suggesting a new bullet? I think it is covered by the last one. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:57: reads reasonably. On 2017/03/27 23:42:06, Matt Giuca wrote: > "if it reads reasonably".. hmm. I think this is subjective in the sense that > lots of people (myself included) (purists if you will!) will tell you that it > never reads reasonably; it is ungrammatical. > > And that is beside the point... we have made an institutional decision that > gender-neutrality is more important than grammatical correctness, and therefore > we should encourage use of singular they even when it is wrong. (Though you > should first try to not involve a pronoun at all.) > > How about simply: "When referring to a person, try using [singular they]." You > could even paraphrase my above paragraph in here if you like. And add the > example from the bullet below that I'm going to tell you to delete: > > "When the user is done, he'll probably..." → "When the user is done, they'll > probably..." Done. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:58: * Try making hypothetical people plural. “When the user is done he’ll On 2017/03/27 23:42:06, Matt Giuca wrote: > I'm personally not a fan of this advice (I'd go with singular they here). > > It's just adding extra confusion to talk about multiple users (for example) when > it's a single-user system. In general you shouldn't change the plurality of a > sentence just to work around the awkwardness of singular they. > > Either embrace singular they (as you already recommend above), or do something > else. I think I disagree. In the example given it seems fine. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:60: → “When users complete this step, they probably…” When referring to a On 2017/03/27 23:42:06, Matt Giuca wrote: > "When referring to a non-person" -- this feels like a separate bullet point. Yep, I think I missed a bullet. Done. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:93: which can be found [here](https://goto.google.com/gender-neutral-code) (sorry, On 2017/03/27 06:58:39, Matt Giuca wrote: > go/... (I think is the preferred way to share internal links publicly) I was wondering about this. Do you have a source for go/ being preferred? The goto.google.com links work on the VPN / phones etc.
lgtm with nits https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... File styleguide/gender_neutral_code.md (right): https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:43: * Content of things like public-domain books. On 2017/03/28 00:56:28, benwells wrote: > On 2017/03/27 06:58:40, Matt Giuca wrote: > > Quotations, and .. > > > > (Maybe a few of these can be combined?) > > Combined this and the quotations one. Acknowledged. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:48: language. On 2017/03/28 00:56:28, benwells wrote: > On 2017/03/27 06:58:40, Matt Giuca wrote: > > indent multi-line bullet points so all the text lines up on Column 3. > > Why? It seems to work as is (when using the markdown command line utility). Easier to read in source form. Optional. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:50: How to change the remaining awkward intrusions of gender: On 2017/03/28 00:56:28, benwells wrote: > On 2017/03/27 23:42:06, Matt Giuca wrote: > > "intrusions" is a weird word. How about "use of". > > I think 'intrusions' conveys the right meaning here. Acknowledged. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:52: * Try rewording things to not involve a pronoun at all. In many cases this makes On 2017/03/28 00:56:28, benwells wrote: > On 2017/03/27 23:42:06, Matt Giuca wrote: > > On 2017/03/27 06:58:39, Matt Giuca wrote: > > > * Avoid anthropomorphism of inanimate objects. Example: "Read an int and put > > him > > > in the list." → "Read an int and put it in the list." > > > > s/inanimate object/non-people (to use a term you used below) > > are you suggesting a new bullet? I think it is covered by the last one. Acknowledged. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:58: * Try making hypothetical people plural. “When the user is done he’ll On 2017/03/28 00:56:27, benwells wrote: > On 2017/03/27 23:42:06, Matt Giuca wrote: > > I'm personally not a fan of this advice (I'd go with singular they here). > > > > It's just adding extra confusion to talk about multiple users (for example) > when > > it's a single-user system. In general you shouldn't change the plurality of a > > sentence just to work around the awkwardness of singular they. > > > > Either embrace singular they (as you already recommend above), or do something > > else. > > I think I disagree. In the example given it seems fine. Acknowledged. https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:93: which can be found [here](https://goto.google.com/gender-neutral-code) (sorry, On 2017/03/28 00:56:28, benwells wrote: > On 2017/03/27 06:58:39, Matt Giuca wrote: > > go/... (I think is the preferred way to share internal links publicly) > > I was wondering about this. Do you have a source for go/ being preferred? The > http://goto.google.com links work on the VPN / phones etc. No, I guess this is fine. https://codereview.chromium.org/2778663002/diff/20001/styleguide/gender_neutr... File styleguide/gender_neutral_code.md (right): https://codereview.chromium.org/2778663002/diff/20001/styleguide/gender_neutr... styleguide/gender_neutral_code.md:17: condescending, and reading biased code isn’t enjoyable. nit: Curly apostrophes (throughout the file). https://codereview.chromium.org/2778663002/diff/20001/styleguide/gender_neutr... styleguide/gender_neutral_code.md:30: comments it implies anthropomorhism of inanimate objects and should be replaced s/morhism/morphism
https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... File styleguide/gender_neutral_code.md (right): https://codereview.chromium.org/2778663002/diff/1/styleguide/gender_neutral_c... styleguide/gender_neutral_code.md:48: language. On 2017/03/28 02:55:32, Matt Giuca wrote: > On 2017/03/28 00:56:28, benwells wrote: > > On 2017/03/27 06:58:40, Matt Giuca wrote: > > > indent multi-line bullet points so all the text lines up on Column 3. > > > > Why? It seems to work as is (when using the markdown command line utility). > > Easier to read in source form. Optional. OK, done. I had a look at other .md files in chrome and it seems to be the typical way it is done. We probably should create a styleguide for .md at some point :) https://codereview.chromium.org/2778663002/diff/20001/styleguide/gender_neutr... File styleguide/gender_neutral_code.md (right): https://codereview.chromium.org/2778663002/diff/20001/styleguide/gender_neutr... styleguide/gender_neutral_code.md:17: condescending, and reading biased code isn’t enjoyable. On 2017/03/28 02:55:33, Matt Giuca wrote: > nit: Curly apostrophes (throughout the file). oops, done. https://codereview.chromium.org/2778663002/diff/20001/styleguide/gender_neutr... styleguide/gender_neutral_code.md:30: comments it implies anthropomorhism of inanimate objects and should be replaced On 2017/03/28 02:55:33, Matt Giuca wrote: > s/morhism/morphism Done.
The CQ bit was checked by benwells@chromium.org
The patchset sent to the CQ was uploaded after l-g-t-m from mgiuca@chromium.org Link to the patchset: https://codereview.chromium.org/2778663002/#ps40001 (title: "Moar Feedback")
CQ is trying da patch. Follow status at https://chromium-cq-status.appspot.com/v2/patch-status/codereview.chromium.or...
The CQ bit was unchecked by benwells@chromium.org
benwells@chromium.org changed reviewers: + brettw@chromium.org
+brettw for owners review. Just realised the styleguide doesn't have owners, and is explicitly excluded by the tbr rule. My plan is to land this, see if it is formatted correctly (no preview) and if all is good will link to it from the main styleguide somehow.
lgtm
The CQ bit was checked by benwells@chromium.org
CQ is trying da patch. Follow status at https://chromium-cq-status.appspot.com/v2/patch-status/codereview.chromium.or...
The CQ bit was unchecked by commit-bot@chromium.org
Try jobs failed on following builders: ios-simulator on master.tryserver.chromium.mac (JOB_TIMED_OUT, build hasn't started yet, builder probably lacks capacity)
The CQ bit was checked by benwells@chromium.org
CQ is trying da patch. Follow status at https://chromium-cq-status.appspot.com/v2/patch-status/codereview.chromium.or...
CQ is committing da patch.
Bot data: {"patchset_id": 40001, "attempt_start_ts": 1490917946008820,
"parent_rev": "26bd6d86d59d2c7227e4359d91852426c80134e2", "commit_rev":
"f6cc2ca5e909933d7cf891f4cece6a9af146655b"}
Message was sent while issue was closed.
Description was changed from ========== Add documentation on keeping code gender neutral. This adds some documentation but doesn't yet link to it from anywhere. BUG=None ========== to ========== Add documentation on keeping code gender neutral. This adds some documentation but doesn't yet link to it from anywhere. BUG=None Review-Url: https://codereview.chromium.org/2778663002 Cr-Commit-Position: refs/heads/master@{#460945} Committed: https://chromium.googlesource.com/chromium/src/+/f6cc2ca5e909933d7cf891f4cece... ==========
Message was sent while issue was closed.
Committed patchset #3 (id:40001) as https://chromium.googlesource.com/chromium/src/+/f6cc2ca5e909933d7cf891f4cece... |
