expressive-code

name

expressive-code

description

Guidance for making source code self-documenting and deciding when comments are appropriate. Covers naming principles for classes, functions, variables, and constants; cases where syntax needs supporting explanation; language-specific documentation styles; and common comment anti-patterns. Use when choosing or reviewing names, documenting complex behavior or contracts, or adding, editing, reviewing, or removing comments. Trigger phrases: "naming principles", "naming conventions", "name this", "rename this", "class name", "function name", "variable name", "constant name", "magic constant", "self-documenting code", "comment style", "add a comment", "write comments", "comment guidelines", "document this", "too many comments", "remove comment", "JSDoc", "Doxygen".

Skill: Expressive Code

Principles

Self-Documenting Code

Prefer clean code over comments. Prefer using language syntax features to emphasize semantics, including:

• Class and type names describe an object's traits.
• Function names describe verbs.
• Variable names describe their purpose.
  • In particular, language constants explain the purpose of values (as opposed to magic constants).

Names

When possible, a name should capture semantics fully.

If the semantics are complex, it might be due to one of the following:

• The entity has too many responsibilities.
• It is impossible or infeasible to divide it further.
  • In this scenario, don't be afraid to use slightly longer names.
  • At the same time, keep in mind that too many long names tend to make code difficult to grasp.