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 Schleifen: Wann eine Pipeline klarer ist und wann nicht
Ein Stream ist eine lazy ausgewertete Pipeline aus Zwischenoperationen, die von einer terminalen Operation abgeschlossen wird; er liest sich gut für filter, map und collect über eine Collection, doch die Paketdokumentation rät von Seiteneffekten in den Lambdas ab, ein Stream lässt sich nicht wiederverwenden, geprüfte Exceptions passen nicht hinein, und bei vorzeitigem Abbruch mit Zustand, indexbasierter Arbeit und Mutation ist eine Schleife klarer.
Maschinenlesbar: JSON