ReadabilityOverCleverness [principle] v1.0.0

Code is read far more often than it is written. When a clever, compact solution and a readable, verbose solution produce the same outcome, prefer the readable one. Cleverness optimizes for the author; readability optimizes for the team.

Optimize code for the reader who will maintain it in six months, not for the author who writes it today. If a colleague cannot understand a function in 60 seconds without running it, the function is too clever.

Applies To

• Naming: longer, descriptive names over abbreviations. getUserByEmailAddress over getUser when the parameter is an email.
• Logic: explicit conditionals over clever one-liners. if (isAdmin) { ... } over isAdmin && doAdminThing().
• Types: explicit type annotations over relying on inference at module boundaries.
• Patterns: standard patterns (factory, builder, strategy) over novel abstractions invented for the occasion.

ReadabilityOverCleverness [principle] v1.0.0

Code is read far more often than it is written. When a clever, compact solution and a readable, verbose solution produce the same outcome, prefer the readable one. Cleverness optimizes for the author; readability optimizes for the team.

Optimize code for the reader who will maintain it in six months, not for the author who writes it today. If a colleague cannot understand a function in 60 seconds without running it, the function is too clever.

Applies To

• Naming: longer, descriptive names over abbreviations. getUserByEmailAddress over getUser when the parameter is an email.
• Logic: explicit conditionals over clever one-liners. if (isAdmin) { ... } over isAdmin && doAdminThing().
• Types: explicit type annotations over relying on inference at module boundaries.
• Patterns: standard patterns (factory, builder, strategy) over novel abstractions invented for the occasion.

Relations

related: [@team/anti-pattern-comment-explaining-bad-code, @team/rule-no-magic-numbers, @team/tradeoff-strict-types-vs-iteration-speed] see-also: [@team/tradeoff-strict-types-vs-iteration-speed]

See Also

• @team/tradeoff-strict-types-vs-iteration-speed