Human Readable Code

Write for a maintainer familiar with the language and project. Reduce the assumptions they must remember and the definitions they must navigate. Optimize for understanding, not line count.

Apply shared principles through each language's idioms. Do not impose one syntax, paradigm, type system, or error model across languages.

Start from use

Read the request, project instructions, nearby code, callers, and relevant tests. Establish inputs, outputs, effects, failures, and compatibility constraints. Sketch a representative call and meaningful normal, boundary, and failure cases; small tasks do not need a separate design document.

Choose data and interfaces from those uses. Start with a direct implementation, using existing facilities before introducing new machinery.

Name concepts consistently

• Use domain vocabulary. Give the same concept the same name; distinguish different concepts.
• Match detail to scope. Local idioms such as i and err can suffice; distant uses need more context. Distinguish roles when nested scopes make indices easy to confuse.
• Name operations for their actions, values for their meaning, and booleans for what true asserts. Avoid ambiguous predicates such as check.
• Expose consequential distinctions: units, inclusive/exclusive bounds, encoding, and validation state. Use names or types without repeating information already clear from context.
• Prefer informative names over long names. Follow established abbreviations and naming conventions.