diff --git a/docs/best-practices/java-coding-guidelines/inclusive_code.md b/docs/best-practices/java-coding-guidelines/inclusive_code.md new file mode 100644 index 000000000..e00adc4bc --- /dev/null +++ b/docs/best-practices/java-coding-guidelines/inclusive_code.md @@ -0,0 +1,32 @@ +# Inclusive Language Standards + +The way we communicate can make the difference between forging positive connections or creating distance in our personal +and professional lives. This includes verbal, written, and non-verbal communications, like body-language. We want our +code to be written with inclusivity in mind. In particular, we try to avoid phrases that can carry hidden meanings. + +The list of phrases contains two types of expressions: gendered or exclusive terms and everyday phrases with racist +origins. This list was developed by our Diversity, Equity, and Inclusion team. This page is a work-in-progress and +therefore can continue to grow. We include these examples below to share guidance for writing inclusive documentation. + + +| Term | Suggested Replacements | +|------------------| ---------------------- | +| Able-bodied | Reinforces dominant norms about physical ability. Suggested alternative: non-disabled. | +| Blackout | "We want to blackout these three dates to allow for a migration to take place. You won’t be able to access the site." This could insinuate that black means "bad"or something negative. Suggested alternatives: Block out, Downtime, Maintenance window | +| Blacklist/whitelist | These phrases may insinuate black means bad and white means good. Suggested alternatives: blocklist/denylist/banlist and allowlist +| Blind/deaf to | Avoid phrases that associate impairments with negative connotations. +| Dummy value/text | Although in this context you may not be referring to a person, the phrase reinforces stereotypes that bodies and minds are defective or less than and that typical abilities are superior. Suggested alternatives: Placeholder, sample or filler. +| Girl/Girls (when referring to women) | Referring to women over 18 years old as a girl has a diminishing effect. Defined by the National Council of Teachers of English as gender-biased, the use of girl in professional contexts has been found to trivialize and patronize women. Instead: Woman or women is a better choice. +| Grandfathering/grandfather clause | A way to exempt some people from a change because of conditions that existed before the change (e.g. we’ve grandfathered some users on an unlimited data plan.”) The term “grandfather clause” originated in the American South in the 1890s as a way to defy the 15th Amendment and prevent black Americans from voting. A good alternative might be “legacy” or "covered under a previous program." +| Guys |Using “guys” to address all people is gendered languages that may insinuate that men are the preferred gender at your organization. Instead: use gender-neutral language such as; folks, people, you all, y’all, and teammates. +| Gypped | Racial slur for being defrauded, swindled or cheated. According to the Oxford English Dictionary, the term is “probably an abbreviation of ‘gypsy,’ a word commonly used to describe the Romani people. +| Handicap | Some disability advocates believe this term is rooted in a correlation between a disabled individual and a beggar, “who had to beg with a cap in his or her hand because of the inability to maintain employment.” Better alternative: Disabled +| Housekeeping | In reference to office work, this language can feel gendered. Suggested alternative: maintenance, cleanup +| Ladies/gals | Terms like “ladies”, “gals” or others can feel patronizing to some. Instead: try women, or “folks” or “people” for mixed-gender groups. +| Master/slave | Problematic term sometimes used to refer to one machine that has the original copy of data and others that automatically update themselves to match its data. Replacements include primary/replica, primary/standby, main/replica +| Nitty-gritty | This term is often used to refer to the “core” or “heart of a matter,” but it was historically a euphemism for the layer of excrement at the bottom of a slave ship after a Trans-Atlantic crossing. +| Sanity check/test | The phrase sanity check is ableist, and unnecessarily references mental health. It denotes that people with mental illnesses are inferior, wrong, or incorrect. Suggested alternatives: Quick check/test, initial check, confidence check, coherence check, soundness check, calibration check, rationality check + + + + diff --git a/docs/best-practices/readme.md b/docs/best-practices/readme.md index 5bcdb4c22..891f5361a 100644 --- a/docs/best-practices/readme.md +++ b/docs/best-practices/readme.md @@ -21,3 +21,6 @@ standards are established by experiment.* [Microservices Best Practices](microservices/readme.md) [Testing Software Intro](testing-software/readme.md) + +[Inclusive Language](java-style-guide/inclusive_code.md) +