Hallo! Heute möchte ich Tipps zum Schreiben von
perfektem, verständlichem Code aus Peter Goodlifs Buch „Das Handwerk eines Programmierers // Die Praxis des Schreibens von gutem Code“ geben.
Natürlich wäre es schön, dieses unterhaltsame Buch jedem vorzulesen, der den Code schreibt, aber für diejenigen, die besonders faul sind, aber aufhören wollen, weniger zu quälen und ihre Kollegen irrezuführen (
ein Gewissen haben ), präsentiere ich
10 Prinzipien des selbstdokumentierenden Codes unter cat
:1. Schreiben Sie einfachen Code mit guter Formatierung
Das Präsentationsformat hat einen großen Einfluss auf das Verständnis des Codes. Eine vernünftige Darstellung vermittelt die Struktur des Codes: Funktionen, Schleifen und bedingte Anweisungen werden klarer.
int fibonacci(int position) { if (position < 2) { return 1; } int previousButOne = 1; int previous = 1; int answer = 2; for (int n = 2; n < position; ++n) { previousButOne = previous; previous = answer; answer = previous + previousButOne; } return answer; }
2. Wählen Sie aussagekräftige Namen
Die Namen aller Variablen, Typen, Dateien und Funktionen sollten aussagekräftig und nicht irreführend sein. Der Name muss korrekt beschreiben, was es ist. Wenn Sie keinen aussagekräftigen Namen finden können, besteht Zweifel daran, ob Sie die Funktionsweise Ihres Codes verstehen.
Das Benennungssystem sollte konsistent sein und keine unangenehmen Überraschungen verursachen. Stellen Sie sicher, dass die Variable immer nur für den Zweck verwendet wird, den der Name vorschlägt.
Eine gute Auswahl an Namen ist wahrscheinlich der beste Weg, um unnötige Kommentare zu vermeiden. Namen ermöglichen es, den Code der Ausdruckskraft natürlicher Sprachen näher zu bringen.
3. Teilen Sie den Code in unabhängige Funktionen auf
Wie Sie den Code in Funktionen aufteilen und welche Namen Sie ihnen geben, kann den Code verständlich oder völlig unverständlich machen.
- Eine Funktion, eine Aktion
Minimieren Sie unerwartete Nebenwirkungen, egal wie nützlich sie erscheinen mögen. Sie benötigen zusätzliche Unterlagen.
Schreiben Sie kurze Funktionen. Sie sind leichter zu verstehen. Sie können in einem komplexen Algorithmus navigieren, wenn dieser in kleine Fragmente mit aussagekräftigen Namen unterteilt ist. Dies ist jedoch in der formlosen Codemasse nicht möglich.
4. Wählen Sie aussagekräftige Typnamen
Beschreiben Sie die Einschränkungen oder das Verhalten so weit wie möglich anhand der verfügbaren Sprachfunktionen. Zum Beispiel:
- Wenn Sie einen Wert bestimmen, der sich nicht ändert, weisen Sie ihm einen Konstantentyp zu (verwenden Sie const in C).
- Wenn die Variable keine negativen Werte annehmen soll, verwenden Sie einen vorzeichenlosen Typ (falls er in der Sprache vorhanden ist).
- Verwenden Sie Aufzählungen, um das zugehörige Dataset zu beschreiben.
- Wählen Sie den Variablentyp richtig aus. Schreiben Sie in C / C ++ Größe in Variablen vom Typ size_t und die Ergebnisse von arithmetischen Operationen mit Zeigern auf Variablen vom Typ ptrdiff_t .
5. Verwenden Sie benannte Konstanten
Code wie
if (counter == 76) ist verwirrend. Was ist die magische Bedeutung von 76? Was bedeutet diese Prüfung? Das Üben magischer Zahlen ist bösartig. Sie verschleiern die Bedeutung des Codes. Es ist viel besser, so zu schreiben:
const size_t bananas_per_cake = 76; ... if (count == bananas_per_cake) { // }
Wenn der konstante 76-Code häufig im Code gefunden wird (entschuldigen Sie,
bananas_per_cake ), wird ein zusätzlicher Vorteil erzielt: Wenn der Inhalt der Bananen in der Torte geändert werden muss, reicht es aus, den Code an einer Stelle zu ändern, anstatt eine globale Suche / Änderung der Nummer 76 durchzuführen, die mit Fehlern behaftet ist.
Dies gilt nicht nur für Zahlen, sondern auch für konstante Zeichenfolgen. Sehen Sie sich
alle Literale in Ihrem Code an, insbesondere wenn sie wiederholt auftreten. Wäre es nicht besser, stattdessen benannte Konstanten zu verwenden?
6. Markieren Sie wichtige Codeteile
Versuchen Sie, wichtigen Code vor dem Hintergrund normalen Materials hervorzuheben. An der richtigen Stelle sollten Sie die Aufmerksamkeit des Lesers auf sich ziehen. Dafür gibt es eine Reihe von Tricks. Zum Beispiel:
- Platzieren Sie Anzeigen mit Bedacht im Klassenzimmer. Erstens sollten Informationen zu geöffneten Objekten angezeigt werden, da sie vom Benutzer der Klasse benötigt werden. Details zur geschlossenen Implementierung sollten am Ende stehen, da sie für die meisten Leser weniger interessant sind.
- Wenn möglich, verstecken Sie alle nicht wesentlichen Informationen. Lassen Sie keinen unnötigen Müll im globalen Namespace. C ++ hat die Redewendung pimpl, mit der Sie die Details der Implementierung der Klasse ausblenden können. (Meyers 97).
- Verstecken Sie keinen wichtigen Code. Schreiben Sie nicht mehr als eine Anweisung in eine Zeile und machen Sie diese Anweisung einfach. Die Sprache ermöglicht es Ihnen, sehr erfinderische Operatoren der for-Schleife zu schreiben, in die die gesamte Logik mit Hilfe vieler Kommas in eine Zeile passt, aber solche Operatoren sind schwer zu lesen. Vermeiden Sie sie.
- Begrenzen Sie die Verschachtelungstiefe von bedingten Anweisungen. Ansonsten ist es schwierig, die Behandlung wirklich wichtiger Fälle hinter einem Haufen von Wenns und Klammern zu bemerken.
7. Kombinieren Sie verwandte Daten
Alle zugehörigen Informationen sollten sich an einem Ort befinden. Andernfalls wird der Leser nicht nur durch Reifen springen, sondern auch mit ESP nach diesen Reifen suchen. Die API für jede Komponente muss durch eine einzelne Datei dargestellt werden. Wenn zu viele miteinander verbundene Informationen vorhanden sind, um an einem Ort dargestellt zu werden, lohnt es sich, die Codearchitektur zu überarbeiten.
Kombinieren Sie Objekte nach Möglichkeit mit Sprachkonstrukten. In C ++ und C # können Sie Elemente im selben
Namespace kombinieren. In Java ist der Bündelungsmechanismus die Paket-Engine. Verwandte Konstanten können in einer Aufzählung definiert werden.
8. Beschriften Sie die Dateien
Platzieren Sie einen Kommentarblock am Anfang der Datei mit einer Beschreibung des Inhalts der Datei und des Projekts, auf das sie sich bezieht. Dies erfordert nicht viel Arbeit, ist aber von großem Nutzen. Jeder, der diese Datei begleiten muss, bekommt eine gute Vorstellung davon, worum es geht. Dieser Titel kann eine besondere Bedeutung haben: Die meisten Softwareunternehmen verlangen aus rechtlichen Gründen, dass jede Quelldatei eine Copyright-Erklärung enthält. In der Regel sehen Datei-Header ungefähr so aus:
/********************************************************* * File: Foo.java * Purpose: Foo class implementation * Notice: (c) 1066 Foo industries. All rights reserved. ********************************************************/
9. Behandeln Sie Fehler richtig
Stellen Sie die Behandlung aller Fehler in den am besten geeigneten Kontext. Wenn beim Lesen / Schreiben auf die Festplatte ein Problem auftritt, muss es in dem Code verarbeitet werden, der den Zugriff auf die Festplatte behandelt. Um diesen Fehler zu beheben, müssen Sie möglicherweise einen weiteren Fehler generieren (z. B. eine Ausnahme "Ich kann die Datei nicht laden"), der an eine höhere Ebene übergeben wird. Dies bedeutet, dass auf jeder Ebene des Programms der Fehler eine genaue Beschreibung des Problems in
seinem Kontext sein muss . Es ist nicht sinnvoll, den Fehler zu behandeln, der mit einem Festplattenfehler im Benutzeroberflächencode verbunden ist.
Selbstdokumentierender Code hilft dem Leser zu verstehen, wo der Fehler aufgetreten ist, was er bedeutet und welche Konsequenzen er für das Programm im Moment hat.
10. Schreiben Sie aussagekräftige Kommentare
Daher haben wir versucht, das Schreiben von Kommentaren mit anderen indirekten Methoden zur Dokumentation von Code zu vermeiden. Nachdem Sie jedoch alle Anstrengungen unternommen haben, um verständlichen Code zu schreiben, muss alles andere mit Kommentaren versehen werden. Um den Code verständlich zu machen, muss er durch eine
angemessene Anzahl von Kommentaren ergänzt werden. Welches?
Versuchen Sie zuerst andere Tricks. Überprüfen Sie beispielsweise, ob Sie den Code durch Ändern des Namens oder durch Erstellen einer Hilfsfunktion klarer machen können, und vermeiden Sie daher Kommentare.
Ich bin sicher, dass Sie nach der Einführung mehrerer dieser Prinzipien in die Gewohnheit einen Programmierer glücklicher machen werden. Und Sie werden dieser glückliche Programmierer sein. Wann? Zum Zeitpunkt der Rückkehr zur Arbeit an seinem Code vor sechs Monaten.