Setting Coding Standards for Inclusive Code

Preface

This post will cover:

• Why inclusive language in code matters
• Problematic terms and their preferred alternatives
• How to implement inclusive coding standards across an organisation

Solution

Inclusive language in coding is about being mindful of the words and phrases used within codebases to promote inclusivity and avoid unintentionally alienating or offending individuals. Setting coding standards for inclusive code requires organisations to adopt guidelines and encourage developers to use more appropriate terminology.

Examples of problematic terms and preferred alternatives:

Problematic Term	Preferred Alternative(s)
Master/Slave	Primary/Replica, Leader/Follower
Blacklist/Whitelist	Denylist/Allowlist, Blocklist/Safelist
Man Hours	Person Hours, Work Hours, Effort Hours
Sanity Check	Consistency Check, Integrity Check, Validation Check
Dummy Variable	Placeholder, Test Variable, Sample Data
Grandfathered	Legacy Status, Exempted, Pre-existing
Native	Built-in, Default, Standard
Killing a Process	Terminating a Process, Stopping a Process
Hang	Freeze, Stop Responding, Unresponsive
Abort	Cancel, Stop, Terminate
White Box Testing	Clear Box Testing, Glass Box Testing
Black Box Testing	Functional Testing, External Testing
Disabled Feature	Inactive Feature, Unavailable Feature
Blind Review	Anonymous Review, Double-Anonymised Review
Master Branch	Main Branch, Default Branch
Slave Database	Read-Replica, Secondary Database
Whitelisted IPs	Allowed IPs, Trusted IPs
Dummy Data	Test Data, Sample Data, Placeholder Data

Why

• Improved Collaboration: Using inclusive terminology helps everyone feel welcome and reduces misunderstandings.
• Future-Proofing: Adopting inclusive language helps to future-proof codebases and aligns with industry trends.
• Better Accessibility: Ensures the codebase is approachable for developers from all backgrounds.
• Reflecting Values: Demonstrates the organisation’s commitment to inclusivity and social responsibility.

Coding Standards Example

Below is a markdown file template you can include in your codebase to set inclusive coding standards.

# Inclusive Coding Standards

## Overview
This file defines acceptable terminology in our codebase to ensure inclusivity and promote positive collaboration.

## Inclusive Language Guidelines
Replace problematic terms with the preferred alternatives listed below:

| Problematic Term | Preferred Alternative(s) |
| ---------------- | ------------------------ |
| Master/Slave     | Primary/Replica, Leader/Follower |
| Blacklist/Whitelist | Denylist/Allowlist, Blocklist/Safelist |
| Man Hours        | Person Hours, Work Hours, Effort Hours |
| Sanity Check     | Consistency Check, Integrity Check, Validation Check |
| Dummy Variable   | Placeholder, Test Variable, Sample Data |
| Grandfathered    | Legacy Status, Exempted, Pre-existing |
| Native           | Built-in, Default, Standard |
| Killing a Process| Terminating a Process, Stopping a Process |
| Hang             | Freeze, Stop Responding, Unresponsive |
| Abort            | Cancel, Stop, Terminate |
| White Box Testing| Clear Box Testing, Glass Box Testing |
| Black Box Testing| Functional Testing, External Testing |
| Disabled Feature | Inactive Feature, Unavailable Feature |
| Blind Review     | Anonymous Review, Double-Anonymised Review |
| Master Branch    | Main Branch, Default Branch |
| Slave Database   | Read-Replica, Secondary Database |
| Whitelisted IPs  | Allowed IPs, Trusted IPs |
| Dummy Data       | Test Data, Sample Data, Placeholder Data |

## Enforcement
- Pull requests must adhere to these guidelines.
- Automated checks will be implemented to flag problematic terms.
- Code reviews will include checking for adherence to these standards.