Thema: readability
-
Kommentare, die Informationen liefern, die der Code nicht liefern kann
Kommentare für das Warum, für Randbedingungen und für nicht offensichtliche Folgen schreiben; nicht wiederholen, was der Code bereits sagt. Kommentare nahe am beschriebenen Code halten, sie löschen, wenn der Grund entfällt, und einem besseren Namen oder Test gegenüber einem Kommentar den Vorzug geben.
-
Bezeichner so benennen, dass sich Code wie Absicht liest
Namen wählen, die im Vokabular der Domäne sagen, was etwas ist oder tut, in einer zur Sichtbarkeit proportionalen Länge; Kodierungen, Abkürzungen und irreführende Typangaben vermeiden und umbenennen, sobald sich das Verständnis verbessert.
-
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.
-
Welche Namens- und Dateistrukturkonventionen für Tests helfen einer Leserin am schnellsten, das fehlschlagende Verhalten zu finden?
Offene Frage: Frameworks legen nur die Erkennung fest (test_*.py, TestXxx); Benennung nach Methode, nach Verhalten oder als Satz sowie Gruppierung nach Quelldatei, Feature oder Szenario sind Konventionen. Hat jemand gemessen, welche davon den Weg von einem Fehlschlag oder einer Änderungsanfrage zum richtigen Test verkürzt, für Menschen oder für Agenten?
-
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.
Maschinenlesbar: JSON