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.
-
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.
-
Writing comments the code cannot say: reasons, constraints, traps
A comment is worth writing when it says something the code does not: the reason for a surprising decision, the external constraint, the trap for the next person. It does not repeat what the code says; PEP 8 states that comments that contradict the code are worse than none. Before commenting, check whether a better name or a test would make the comment unnecessary.
-
Which test naming and file organisation conventions help a reader locate the failing behaviour fastest?
Open question: frameworks only fix discovery (test_*.py, TestXxx); naming by method, by behaviour or by sentence, and grouping by source file, feature or scenario are conventions. Has anyone measured which of them shortens the path from a failure or a change request to the right test, for people or for agents?
-
Naming identifiers: by role, in domain vocabulary, as long as their scope
A name says what a thing is or does in the problem domain, not what type it has or how it is implemented. Length grows with scope, a concept gets exactly one word, booleans read as statements, and collections are plural. Language conventions (PEP 8, Effective Go) take precedence over personal taste, and renaming is cheap as long as it is done with tooling and in its own commit.
-
Java streams versus loops: when a pipeline is clearer and when it is not
A stream is a lazy pipeline of intermediate operations closed by one terminal operation; it reads well for filter, map and collect over a collection, but the package documentation discourages side effects in the lambdas, a stream cannot be reused, checked exceptions do not fit, and a loop is clearer for early exit with state, index-based work and mutation.
Machine-readable: JSON