styleguide/inclusive_code.md

   1 # Inclusive Chromium code
   2
   3 ## Why this is important
   4
   5 Our [Code of Conduct](https://www.chromium.org/conduct) under "Be respectful and
   6 constructive" says:
   7
   8 > Each of us has the right to __enjoy our experience__ and participate without
   9 > fear of harassment, __discrimination__, or __condescension__, whether blatant
  10 > or subtle.
  11
  12 Emphasis is added: unnecessarily exclusive code is discriminatory and
  13 condescending, and reading biased code isn't enjoyable.
  14
  15 ## Gender-Neutral
  16
  17 Some points in our code, documentation and comments contain needless assumptions
  18 about the gender of a future reader, user, etc. __Example: "When the user logs
  19 into his profile."__
  20
  21 ### Suggestions on how to keep code gender-neutral
  22
  23 These are only suggestions. You make the call.
  24
  25 Things to avoid:
  26
  27 * Gendered pronouns: he / she / him / her / his / hers, etc.
  28 * Instances of the phrases "he or she", "his/hers", "(s)he", etc. All of these
  29   still exclude those who don't identify with either gender, and implicitly
  30   (slightly) favor one gender via listing it first.
  31 * "Guys" as a gender-neutral term, which has male associations. Usually in
  32   comments it implies anthropomorphism of inanimate objects and should be
  33   replaced with a more precise technical term. If it does refer to people,
  34   consider using "everyone", "folks", "people", "peeps", "y'all", etc.
  35 * Other gendered words: "brother", "mother", "man", etc.
  36
  37 Cases that are likely fine to leave alone include:
  38
  39 * References to a specific person ("Rachel is on leave; update this when she is
  40   back.").
  41 * A name ("Guy" and "He" are both valid names).
  42 * A language code ("he" is the ISO 639-1 language code for Hebrew).
  43 * He as an abbreviation for "helium".
  44 * The Spanish word "he".
  45 * References to a specific fictional person ([Alice, Bob, ...](http://en.wikipedia.org/wiki/Alice_and_Bob)).
  46   * For new code/comments, consider using just 'A', 'B' as names.
  47 * Quotations and content of things like public-domain books.
  48 * Partner agreements and legal documents we can no longer edit.
  49 * Occurrences in randomly generated strings or base-64 encodings.
  50 * Content in a language other than English unless you are fluent in that
  51   language.
  52
  53 How to change the remaining awkward intrusions of gender:
  54
  55 * Try rewording things to not involve a pronoun at all. In many cases this makes
  56   the documentation clearer. Example: "I tell him when I am all done." → "I tell
  57   the owner when I am all done." This saves the reader a tiny bit of mental
  58   pointer-dereferencing.
  59 * Try using [singular they](https://en.wikipedia.org/wiki/Singular_they).
  60 * Try making hypothetical people plural. "When the user is done he'll
  61   probably..."
  62 → "When users complete this step, they probably...".
  63 * When referring to a 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)).
  64
  65 ### Example changelists
  66
  67 For a long list of changes, see [this bug](https://crbug.com/542537). Some
  68 examples:
  69
  70 * [Make some code gender neutral](https://crrev.com/e3496e19094cf7e711508fe69b197aa13725c790)
  71 * [Updates comments in the src files to remove gender specific terms](https://crrev.com/5b9d52e8a6ec9c11a675bae21c7d1b0448689fb6)
  72 * [Gender-neutralize a few more comments / strings](https://crrev.com/993006d919c7b0d3e2309041c1e45b8d7fc7ff0e)
  73 * [Make some android code gender neutral](https://crrev.com/93d83ac96c3d1c27be9ea7e842b25b3dded2550b)
  74
  75 ### Tools
  76
  77 * [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)
  78   is a code search link prepopulated with a search that finds a lot of gendered
  79   terms.
  80 * To search for files containing gendered terms, use this command (or a variant
  81   of it):
  82 ```
  83 git grep -wiEIl \ '(he)|(she)|(his)|(hers)|(him)|(her)|(guy)|(guys)'
  84 ```
  85 * To search in a file open in vim for gendered terms, use this command:
  86 ```
  87 /\<he\>\|\<she\>\|\<his\>\|\<hers\>\|\<him\>\|\<her\>\|\<guy\>\|\<guys\>|\<man\>\c
  88 ```
  89 * There are presubmit checks available for this that are run for the infra and
  90   v8 repos. They are not run for other repos as there are too many false
  91   positives.
  92
  93 ## Racially neutral
  94
  95 Terms such as "blacklist" and "whitelist" reinforce the notion that black==bad
  96 and white==good. [That Word *Black*, by Langston
  97 Hughes](https://mcwriting11.blogspot.com/2014/06/that-word-black-by-langston-hughes.html)
  98 illustrates this problem in a lighthearted, if somewhat pointed way.
  99
 100 These terms can usually be replaced by "blocklist" and "allowlist" without
 101 changing their meanings, but particular instances may need other replacements.
 102
 103 ### Example changelists
 104
 105 For a long list of changes, see [this bug](https://crbug.com/842296). Some
 106 examples:
 107
 108 * ["Blacklist"->"Blocklist" in interventions-internals UI.](https://crrev.com/c/1055905)
 109 * [Remove "whitelist" and "blacklist" from extension docs.](https://crrev.com/c/1056027)
 110 * [Declarative Net Request: Replace usages of 'blacklist' and 'whitelist'.](https://crrev.com/c/1094141)
 111
 112 ## Thanks
 113
 114 This document is based on an internal Google document by Rachel Grey and others,
 115 which can be found [here](https://goto.google.com/gender-neutral-code) (sorry,
 116 Googlers only).