inclusive-language（包容性语言）

Inclusive Language

Overview

Use respectful, accessible language in all code and documentation.

Core principle: Words matter. Use inclusive terminology.

This applies to: Code, comments, documentation, commit messages, branch names, and all text.

Terminology Guide

Branch Names

# Correct
git checkout main
git push origin main

# Repository default branch should be 'main'

Access Control

// Correct
const allowlist = ['admin@example.com', 'user@example.com'];
const denylist = ['spam@example.com'];

function isAllowed(email: string): boolean {
  return allowlist.includes(email) && !denylist.includes(email);
}

Primary/Secondary

// Correct
interface DatabaseConfig {
  primary: ConnectionString;
  replicas: ConnectionString[];
}

class ReplicationManager {
  private leader: Node;
  private followers: Node[];
}

Gendered Terms

// Correct
/**
 * When a user logs in, they receive a session token.
 * The user can then use their token to access resources.
 */

Ability-Related

// Correct
function validateInput(data: unknown): boolean {
  // Perform validity check on input data
}

// Instead of "sanity check"
function confidenceCheck(result: Result): boolean {
  // Verify result is within expected bounds
}

Violence-Related

// Correct
function terminateProcess(pid: number): void { }
function stopServer(): void { }
function cancelRequest(id: string): void { }

// Acceptable (industry standard)
function executeQuery(sql: string): Result { }

Other Terms

Examples in Context

Configuration

// Correct
interface FeatureFlags {
  allowlist: string[];
  denylist: string[];
}

const replicationConfig = {
  primary: 'db-primary.example.com',
  replicas: [
    'db-replica-1.example.com',
    'db-replica-2.example.com',
  ],
};

Documentation

<!-- Correct -->
# Getting Started

When a user creates an account, they will receive a confirmation email.
They can then set up their profile using their preferred settings.

## Access Control

Use the allowlist to specify approved domains.
Use the denylist to block specific addresses.

Comments

// Correct
// Validity check: ensure the input meets expected format
if (!isValidFormat(input)) {
  throw new ValidationError('Input format is invalid');
}

// Confidence check: verify result is within expected bounds
if (result > MAX_EXPECTED || result < MIN_EXPECTED) {
  logger.warn('Result outside expected range');
}

Error Messages

// Correct
throw new Error('Email address is on the denylist');
throw new Error('Origin not in allowlist');
throw new Error('Request terminated due to timeout');

Applying to Existing Code

When modifying existing code with non-inclusive terms:

Small Scope (Same File)

If you're modifying a function that uses non-inclusive language:

1. Rename the term as part of your change
2. Update related documentation
3. Note in commit message: "Renamed to inclusive terminology"

Large Scope (Multiple Files)

If renaming would touch many files:

1. Create a separate issue for the terminology update
2. Complete current work with existing terms
3. Schedule terminology update as future work

API/Public Interface

If the term is in a public API:

1. Document the plan for deprecation
2. Add deprecated alias with new term
3. Migrate users over time
4. Remove deprecated term in major version

// Transition approach
/** @deprecated Use allowlist instead */
export const whitelist = allowlist;

export const allowlist: string[] = [];

Commit Messages and Branch Names

# Branch names
feature/issue-123-add-denylist-support  # Correct
fix/issue-456-update-replica-config     # Correct

# Commit messages
"Add email denylist validation"         # Correct
"Update replica failover logic"         # Correct

Checklist

When writing or reviewing code:

• No master/slave terminology
• No whitelist/blacklist terminology
• No gendered language for generic users
• No ability-related negative terms
• Documentation uses inclusive language
• Variable/function names are inclusive
• Error messages are inclusive
• Comments are inclusive

Resources

• Google Developer Style Guide: https://developers.google.com/style/inclusive-documentation
• Inclusive Naming Initiative: https://inclusivenaming.org/

Integration

This skill is applied by:

• issue-driven-development - Step 7
• comprehensive-review - Style criterion

This skill ensures:

• Welcoming codebase
• Professional standards
• Accessibility for all contributors