Add documentation on keeping code gender neutral.

styleguide/gender_neutral_code.md

Index: styleguide/gender_neutral_code.md
diff --git a/styleguide/gender_neutral_code.md b/styleguide/gender_neutral_code.md
new file mode 100644
index 0000000000000000000000000000000000000000..5b81a52b24164681c5131fc323db42d12ba30162
--- /dev/null
+++ b/styleguide/gender_neutral_code.md
@@ -0,0 +1,94 @@
+# Gender-neutral Chromium code
+
+## Why this is important
+
+Some points in our code, documentation and comments contain needless assumptions
+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 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.

+into his profile.”__
+
+Our [Code of Conduct](https://www.chromium.org/conduct) under “Be respectful and
+constructive” says:
+
+> Each of us has the right to __enjoy our experience__ and participate without
+> fear of harassment, __discrimination__, or __condescension__, whether blatant
+> or subtle.
+
+Emphasis is added: unnecessarily gendered code is discriminatory and
+condescending, and reading biased code isn’t enjoyable.
+
+## Suggestions on how to keep code gender-neutral
+
+These are only suggestions. You make the call. 
+
+Things to avoid:
+
+* Gendered pronouns: he / she / him / her / his / hers, etc.
+* Instances of the phrases “he or she”, “his/hers”, “(s)he”, etc. All of these
+still exclude those who don’t identify with either gender, and implicitly
+(slightly) favor one gender via listing it first.
+* “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 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.

+avoid by using “everyone”, “folks”, “people”, “peeps”, “y’all”, etc. 
+* Other gendered words: “brother”, “mother”, “man”, etc.
+
+Cases that are likely fine to leave alone include:
+
+* References to a specific person (“Rachel is on leave; update this when she is
+back.”).
+* A name ("Guy" and "He" are both valid names).
+* A language code (“he” is the ISO 639-1 language code for Hebrew).
+* He as an abbreviation for “helium”.
+* The Spanish word “he”.
+* 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, ..."

[benwells, 2017/03/28 00:56:28]

Done.

+    * For new code/comments, consider using just ‘A’, ‘B’ as names.

[Matt Giuca, 2017/03/27 06:58:40]

2-space indent.

[benwells, 2017/03/28 00:56:28]

Done, let's see if it is recognized as an indent...

+* Content of things like public-domain books.

[Matt Giuca, 2017/03/27 06:58:40]

Quotations, and ..

(Maybe a few of these can be combined?)

[benwells, 2017/03/28 00:56:28]

Combined this and the quotations one.

[Matt Giuca, 2017/03/28 02:55:32]

Acknowledged.

+* Partner agreements and legal documents we can no longer edit.
+* Occurrences in randomly generated strings or base-64 encodings.
+* Quotations from other non-chromium material, such as external documentation.

[Matt Giuca, 2017/03/27 06:58:39]

Capital C Chromium.

[benwells, 2017/03/28 00:56:28]

Removed this line.

+* Content in a language other than English unless you are fluent in that
+language.

[Matt Giuca, 2017/03/27 06:58:40]

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 markdown command line utility).

[Matt Giuca, 2017/03/28 02:55:32]

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 chrome and it seems to be the
typical way it is done. We probably should create a styleguide for .md at some
point :)

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

[benwells, 2017/03/28 00:56:28]

I think 'intrusions' conveys the right meaning here.

[Matt Giuca, 2017/03/28 02:55:32]

Acknowledged.

+
+* 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. 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 used below)

[benwells, 2017/03/28 00:56:28]

are you suggesting a new bullet? I think it is covered by the last one.

[Matt Giuca, 2017/03/28 02:55:32]

Acknowledged.

+the documentation clearer. Example: "I tell him when I am all done." → "I tell
+the owner when I am all done." This saves the reader a tiny bit of mental
+pointer-dereferencing.
+* Try using [singular they](https://en.wikipedia.org/wiki/Singular_they), if it
+reads reasonably.

[Matt Giuca, 2017/03/27 23:42:06]

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

+* 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 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 fine.

[Matt Giuca, 2017/03/28 02:55:32]

Acknowledged.

+probably...”
+→ “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 like a separate bullet point.

[benwells, 2017/03/28 00:56:28]

Yep, I think I missed a bullet. Done.

+non-person, “it” or “one” may be good alternatives ([wikipedia link](http://wikipedia.org/wiki/Gender-specific_and_gender-neutral_pronouns#It_and_one_as_gender-neutral_pronouns)).
+
+## Example changelists
+
+For a long list of changes, see [this bug](https://crbug.com/542537). Some
+examples:
+
+* [Make some code gender neutral](https://crrev.com/e3496e19094cf7e711508fe69b197aa13725c790)
+* [Updates comments in the src files to remove gender specific terms](https://crrev.com/5b9d52e8a6ec9c11a675bae21c7d1b0448689fb6)
+* [Gender-neutralize a few more comments / strings](https://crrev.com/993006d919c7b0d3e2309041c1e45b8d7fc7ff0e)
+* [Make some android code gender neutral](https://crrev.com/93d83ac96c3d1c27be9ea7e842b25b3dded2550b)
+
+## Tools
+
+* [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)
+is a code search link prepopulated with a search that finds a lot of gendered
+terms.
+* To search for files contained gendered terms, use this command (or a variant

[Matt Giuca, 2017/03/27 23:42:06]

s/contained/containing

+of it):
+```
+git grep -wiEIl \ '(he)|(she)|(his)|(hers)|(him)|(her)|(guy)|(guys)'
+```
+* To search in a file open in vim for gendered terms, use this command:
+```
+/\<he\>\|\<she\>\|\<his\>\|\<hers\>\|\<him\>\|\<her\>\|\<guy\>\|\<guys\>|\<man\>\c
+```
+* There are presubmit checks available for this that are run for the infra and
+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 2 spaces?

+
+## Thanks
+
+This document is based on an internal Google document by Rachel Grey and others,
+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 internal links publicly)

[benwells, 2017/03/28 00:56:28]

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.

+Googler only).