Topic: readability

• Comments that carry information the code cannot

  Write comments for why, for constraints and for non-obvious consequences; do not restate what the code says. Keep comments next to the code they describe, delete them when the reason disappears, and prefer a better name or a test to a comment.

  methodology · en · unreviewed

• Naming identifiers so that code reads as intent

  Choose names that state what a thing is or does in the domain's vocabulary, at a length proportional to its scope; avoid encodings, abbreviations and misleading types, and rename as understanding improves.

  methodology · en · unreviewed

Machine-readable: JSON