styleguide/gender_neutral_code.md - Issue 2778663002: Add documentation on keeping code gender neutral.

Side by Side Diff: styleguide/gender_neutral_code.md

Issue 2778663002: Add documentation on keeping code gender neutral. (Closed)

Patch Set: Created 3 years, 8 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

OLD	NEW
(Empty)
	1 # Gender-neutral Chromium code

	2

	3 ## Why this is important

	4

	5 Some points in our code, documentation and comments contain needless assumptions

	6 about the gender of a future reader, user, etc. __Example: “When the user logs
	Matt Giuca 2017/03/27 06:58:39 nit: Do you think you should change the curly quot 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. benwells 2017/03/28 00:56:28 Done. Show quoted text 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.
	7 into his profile.”__

	8

	9 Our [Code of Conduct](https://www.chromium.org/conduct) under “Be respectful and

	10 constructive” says:

	11

	12 > Each of us has the right to __enjoy our experience__ and participate without

	13 > fear of harassment, __discrimination__, or __condescension__, whether blatant

	14 > or subtle.

	15

	16 Emphasis is added: unnecessarily gendered code is discriminatory and

	17 condescending, and reading biased code isn’t enjoyable.

	18

	19 ## Suggestions on how to keep code gender-neutral

	20

	21 These are only suggestions. You make the call.

	22

	23 Things to avoid:

	24

	25 * Gendered pronouns: he / she / him / her / his / hers, etc.

	26 * Instances of the phrases “he or she”, “his/hers”, “(s)he”, etc. All of these

	27 still exclude those who don’t identify with either gender, and implicitly

	28 (slightly) favor one gender via listing it first.

	29 * “Guys” as a gender-neutral term. This has male associations and is easy to
	Matt Giuca 2017/03/27 06:58:40 "..., which has male associations. Usually, it imp "..., 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", ..." benwells 2017/03/28 00:56:28 Done. Show quoted text 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.
	30 avoid by using “everyone”, “folks”, “people”, “peeps”, “y’all”, etc.

	31 * Other gendered words: “brother”, “mother”, “man”, etc.

	32

	33 Cases that are likely fine to leave alone include:

	34

	35 * References to a specific person (“Rachel is on leave; update this when she is

	36 back.”).

	37 * A name ("Guy" and "He" are both valid names).

	38 * A language code (“he” is the ISO 639-1 language code for Hebrew).

	39 * He as an abbreviation for “helium”.

	40 * The Spanish word “he”.

	41 * References to a specific fictional person ([Alice, Bob...](http://en.wikipedia .org/wiki/Alice_and_Bob)).
	Matt Giuca 2017/03/27 23:42:06 nit: "Bob, ..." nit: "Bob, ..." benwells 2017/03/28 00:56:28 Done. Show quoted text On 2017/03/27 23:42:06, Matt Giuca wrote: > nit: "Bob, ..." Done.
	42 * For new code/comments, consider using just ‘A’, ‘B’ as names.
	Matt Giuca 2017/03/27 06:58:40 2-space indent. 2-space indent. benwells 2017/03/28 00:56:28 Done, let's see if it is recognized as an indent.. Show quoted text On 2017/03/27 06:58:40, Matt Giuca wrote: > 2-space indent. Done, let's see if it is recognized as an indent...
	43 * Content of things like public-domain books.
	Matt Giuca 2017/03/27 06:58:40 Quotations, and .. (Maybe a few of these can be c Quotations, and .. (Maybe a few of these can be combined?) benwells 2017/03/28 00:56:28 Combined this and the quotations one. Show quoted text 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. Matt Giuca 2017/03/28 02:55:32 Acknowledged. Show quoted text 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.
	44 * Partner agreements and legal documents we can no longer edit.

	45 * Occurrences in randomly generated strings or base-64 encodings.

	46 * Quotations from other non-chromium material, such as external documentation.
	Matt Giuca 2017/03/27 06:58:39 Capital C Chromium. Capital C Chromium. benwells 2017/03/28 00:56:28 Removed this line. Show quoted text On 2017/03/27 06:58:39, Matt Giuca wrote: > Capital C Chromium. Removed this line.
	47 * Content in a language other than English unless you are fluent in that

	48 language.
	Matt Giuca 2017/03/27 06:58:40 indent multi-line bullet points so all the text li indent multi-line bullet points so all the text lines up on Column 3. benwells 2017/03/28 00:56:28 Why? It seems to work as is (when using the markdo Show quoted text 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). Matt Giuca 2017/03/28 02:55:32 Easier to read in source form. Optional. Show quoted text 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. benwells 2017/03/28 03:14:05 OK, done. I had a look at other .md files in chrom Show quoted text 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 :)
	49

	50 How to change the remaining awkward intrusions of gender:
	Matt Giuca 2017/03/27 23:42:06 "intrusions" is a weird word. How about "use of". "intrusions" is a weird word. How about "use of". benwells 2017/03/28 00:56:28 I think 'intrusions' conveys the right meaning her Show quoted text 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. Matt Giuca 2017/03/28 02:55:32 Acknowledged. Show quoted text 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.
	51

	52 * Try rewording things to not involve a pronoun at all. In many cases this makes
	Matt Giuca 2017/03/27 06:58:39 * Avoid anthropomorphism of inanimate objects. Exa * Avoid anthropomorphism of inanimate objects. Example: "Read an int and put him in the list." → "Read an int and put it in the list." Matt Giuca 2017/03/27 23:42:06 s/inanimate object/non-people (to use a term you u Show quoted text 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) benwells 2017/03/28 00:56:28 are you suggesting a new bullet? I think it is cov Show quoted text 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. Matt Giuca 2017/03/28 02:55:32 Acknowledged. Show quoted text 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.
	53 the documentation clearer. Example: "I tell him when I am all done." → "I tell

	54 the owner when I am all done." This saves the reader a tiny bit of mental

	55 pointer-dereferencing.

	56 * Try using [singular they](https://en.wikipedia.org/wiki/Singular_they), if it

	57 reads reasonably.
	Matt Giuca 2017/03/27 23:42:06 "if it reads reasonably".. hmm. I think this is su "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..." benwells 2017/03/28 00:56:28 Done. Show quoted text 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.
	58 * Try making hypothetical people plural. “When the user is done he’ll
	Matt Giuca 2017/03/27 23:42:06 I'm personally not a fan of this advice (I'd go wi 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. benwells 2017/03/28 00:56:27 I think I disagree. In the example given it seems Show quoted text 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. Matt Giuca 2017/03/28 02:55:32 Acknowledged. Show quoted text 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.
	59 probably...”

	60 → “When users complete this step, they probably…” When referring to a
	Matt Giuca 2017/03/27 23:42:06 "When referring to a non-person" -- this feels lik "When referring to a non-person" -- this feels like a separate bullet point. benwells 2017/03/28 00:56:28 Yep, I think I missed a bullet. Done. Show quoted text 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.
	61 non-person, “it” or “one” may be good alternatives ([wikipedia link](http://wiki pedia.org/wiki/Gender-specific_and_gender-neutral_pronouns#It_and_one_as_gender- neutral_pronouns)).

	62

	63 ## Example changelists

	64

	65 For a long list of changes, see [this bug](https://crbug.com/542537). Some

	66 examples:

	67

	68 * [Make some code gender neutral](https://crrev.com/e3496e19094cf7e711508fe69b19 7aa13725c790)

	69 * [Updates comments in the src files to remove gender specific terms](https://cr rev.com/5b9d52e8a6ec9c11a675bae21c7d1b0448689fb6)

	70 * [Gender-neutralize a few more comments / strings](https://crrev.com/993006d919 c7b0d3e2309041c1e45b8d7fc7ff0e)

	71 * [Make some android code gender neutral](https://crrev.com/93d83ac96c3d1c27be9e a7e842b25b3dded2550b)

	72

	73 ## Tools

	74

	75 * [Here](https://cs.chromium.org/search/?q=%28%5E%7C%5Cs%7C%5C%28%7C%5C%5B%29%28 %5BHh%5De%7C%5BSs%5Dhe%7C%5BHh%5Dis%7C%5BHh%5Ders?%7C%5BHh%5Dim%7C%5BHh%5Der%7C% 5BGg%5Duys?%29%5Cb&sq=package:chromium&type=cs)

	76 is a code search link prepopulated with a search that finds a lot of gendered

	77 terms.

	78 * To search for files contained gendered terms, use this command (or a variant
	Matt Giuca 2017/03/27 23:42:06 s/contained/containing s/contained/containing
	79 of it):

	80 ```

	81 git grep -wiEIl \ '(he)\|(she)\|(his)\|(hers)\|(him)\|(her)\|(guy)\|(guys)'

	82 ```

	83 * To search in a file open in vim for gendered terms, use this command:

	84 ```

	85 /\<he\>\\|\<she\>\\|\<his\>\\|\<hers\>\\|\<him\>\\|\<her\>\\|\<guy\>\\|\<guys\>\|\<man\> \c

	86 ```

	87 * There are presubmit checks available for this that are run for the infra and

	88 v8 repos. They are not run for other repos as there are too many false positives .
	Matt Giuca 2017/03/27 06:58:39 nit: Word wrap. Also shouldn't line 88 be indented nit: Word wrap. Also shouldn't line 88 be indented 2 spaces?
	89

	90 ## Thanks

	91

	92 This document is based on an internal Google document by Rachel Grey and others,

	93 which can be found [here](https://goto.google.com/gender-neutral-code) (sorry,
	Matt Giuca 2017/03/27 06:58:39 go/... (I think is the preferred way to share inte go/... (I think is the preferred way to share internal links publicly) benwells 2017/03/28 00:56:28 I was wondering about this. Do you have a source f Show quoted text 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. Matt Giuca 2017/03/28 02:55:32 No, I guess this is fine. Show quoted text 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.
	94 Googler only).

OLD	NEW

« no previous file with comments | « no previous file | no next file » | no next file with comments »