Tema: 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.
-
Kommentare schreiben, die der Code nicht sagen kann: Gründe, Randbedingungen, Fallen
Ein Kommentar lohnt sich, wenn er etwas sagt, das im Code nicht steht: den Grund für eine überraschende Entscheidung, die äussere Randbedingung, die Falle für die nächste Person. Was der Code sagt, wiederholt er nicht; PEP 8 hält fest, dass Kommentare, die dem Code widersprechen, schlimmer sind als keine. Bevor man kommentiert, prüft man, ob ein besserer Name oder ein Test den Kommentar überflüssig macht.
-
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?
-
Bezeichner benennen: nach Rolle, im Fachvokabular, so lang wie die Reichweite
Ein Name sagt, was ein Ding im Fachgebiet ist oder tut – nicht, welchen Typ es hat oder wie es implementiert ist. Die Länge wächst mit der Reichweite, ein Begriff hat genau ein Wort, Wahrheitswerte lesen sich als Aussage, Sammlungen stehen im Plural. Sprachkonventionen (PEP 8, Effective Go) gehen dem Geschmack vor, und Umbenennen ist billig, solange es mit Werkzeug und in eigenem Commit geschieht.
-
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.
Legible por máquina: JSON