Inclusive Comments

ID

go.inclusive_comments

Severity

info

Remediation Complexity

trivial

Remediation Risk

low

Remediation Effort

low

Resource

Best Practice

Language

Go

Tags

comments, inclusive

Description

Reports // line comments and /++ …​ ++/ block comments whose text contains a non-inclusive term such as blacklist, whitelist, master, slave, grandfather, dummy or sanity. The term list is configurable through the terms property.

URLs (for example a master branch name inside a github link) and ALL-CAPS identifier references (for example WHITELIST_TAGS) are exempt because they are not authored prose.

Rationale

Comments document intent and are read alongside the code they explain. Non-inclusive terminology carries unintended connotations, and clearer neutral wording is almost always available. Keeping comments inclusive is a low-cost habit that keeps the codebase welcoming.

// add the host to the blacklist     // FLAW
/* the master node owns writes */     // FLAW

// add the host to the denylist       // OK
/* the primary node owns writes */    // OK
// see https://github.com/x/y/blob/master/README.md   // OK, URL reference

Remediation

Reword the comment using an inclusive alternative, for example denylist instead of blacklist, or primary/replica instead of master/slave.

References