Styleguide
Kommentare
Die Delphi-Sprache unterstützt zwei Kommentar-Arten: Block- und einzeilige Kommentare. Einige generelle Richtlinien für die Verwendung von Kommentaren:
- Es ist hilfreich, Kommentare am Anfang einer Unit zu platzieren, um ihren Zweck zu erklären.
- Es ist hilfreich, Kommentare vor einer Klassendeklaration zu platzieren.
- Es ist hilfreich, Kommentare vor einigen Methodendeklarationen zu platzieren.
- Vermeiden Sie überflüssige Kommentare:
i := i + 1; // Add one to i
- Erkennen Sie, dass irreführende Kommentare schlechter sind als überhaupt keine Kommentare.
- Vermeiden Sie es, Informationen in Kommentare einzubinden, die wahrscheinlich bald überholt sind.
- Vermeiden Sie es, Kommentare in aus Sterchnen oder sonstigen Sonderzeichen gezeichnete Rahmen einzuschließen.
- Temporäre Kommentare, von denen zu erwarten ist, dass sie später geändert oder gelöscht werden, sollen mit der speziellen Kennzeichnung „???:“ markiert werden, so dass sie später schnell gefunden werden können. Idealerweise sollten alle temporären Kommentare entfernt werden, sobald ein Programm fertig zur Auslieferung ist.
Beispiel:
// ???: Change this to call Sort when it is fixed List.MySort;
Kommentarblöcke
Die Delphi-Sprache unterstützt zwei Arten von Kommentarblöcken. Das am häufigsten Verwendete Kommentarblockzeichen ist ein Paar geschweifter Klammern { }. Das Delphi-Team zieht es vor, Kommentare dieser Art selten und so einfach wie möglich einzusetzen. Zum Beispiel sollten Sie es vermeiden, mit Sternchen Muster oder Linien innerhalb des Codes zu erstellen. Machen Sie stattdessen Gebrauch von Leerzeichen, um Ihre Kommentare mehr aufzuteilen, als Sie es in einem Textverarbeitungsdokument tun würden. Die Worte in Ihrem Kommentar sollten in derselben Zeile beginnen wie die geschweifte Klammer wie in diesem Ausschnitt aus DsgnIntf.pas gezeigt:
{ TPropertyEditor Edits a property of a component, or list of components, selected into the Object Inspector. The property editor is created based on the type of the property being edited as determined by the types registered by... etc... GetXxxValue Gets the value of the first property in the Properties property. Calls the appropriate TProperty GetXxxValue method to retrieve the value. SetXxxValue Sets the value of all the properties in the Properties property. Calls the appropriate TProperty SetXxxxValue methods to set the value. }
Ein Kommentarblock wird ebenfalls für den Copyright-/ID-Kommentar am Anfang jeder Quelldatei verwendet. Es ist ebenfalls gebräuchlich, einzelne Codezeilen „auszukommentieren“.
Kommentarblöcke, die eine Methode beschreiben, sollten vor der Methodendeklaration stehen.
Beispiel:
// RICHTIG { TMyObject.MyMethod Diese Routine erlaubt Ihnen, den Code auszuführen. } procedure TMyObject.MyMethod; begin end; // FALSCH procedure TMyObject.MyMethod; {****************************************************** TMyObject.MyMethod Diese Routine erlaubt Ihnen, den Code auszuführen. *******************************************************} begin end;
Eine zweite Art von Kommentarblöcken enthält zwei Zeichen, eine Klammer und einen Stern (* *). Sie wird manchmal „starparen comments“ genannt. Diese Kommentare sind grundsätzlich nur während der Code-Entwicklung nützlich, wo ihr primärer Nutzen darin besteht, dass sie das Verschachteln von Kommentaren erlauben, solange die Verschachtelungsebene kleiner als zwei ist. Die Delphi-Sprache unterstützt nicht das Verschachteln gleichartiger Kommentare untereinander, weshalb es in Wirklichkeit nur eine Kommentarverschachtelungsebene gibt: Geschweifte Klammern innerhalb von Sternklammern und Sternklammern innerhalb von geschwiften Klammern. Solange Sie sie nicht verschachteln, wird jeder andere Standard-Pascal-Kommentar innerhalb eines Kommentars der gleichen Art ignoriert. Als Ergebnis können Sie die Kommentarsyntax verwenden, um ein großes Stück Code, das gemischt ist aus Code und Kommentaren, auszukommentieren:
(* procedure TForm1.Button1Click(Sender: TObject); begin DoThis; // Start the process DoThat; // Continue iteration { We need a way to report errors here, perhaps using a try finally block ??? } CallMoreCode; // Finalize the process end; *)
In diesem Beispiel ist die vollständige Button1Click-Methode auskommentiert, einschließlich aller Unterkommentare, die sich zwischen dem Begin..End-Paar der Prozedur befinden.
Einzeilige Kommentare
Einzeilige Kommentare bestehen aus den Zeichen // gefolgt von Text. Fügen Sie zwischen // und den eigentlichen Kommentar ein Leerzeichen ein. Platzieren Sie einzeilige Kommentare in derselben Einrückungsebene wie den darauf folgenden Code. Sie können einzeilige Kommentare gruppieren, um einen größeren Kommentar zu bilden.
Einem einzeiliger Kommentar oder einer Kommentargruppe sollte immer eine Leerzeile vorausgehen, außer es handelt sich um die erste Zeile innerhalb eines Blockes. Wenn sich der Kommentar auf eine Gruppe einzelner Anweisungen bezieht, sollte dem Kommentar oder der Kommentargruppe eine Leerzeile folgen. Wenn er sich nur auf die nächste Anweisung bezieht (welche eine zusammengesetzte Anweisung sein kann), folgt ihm keine Leerzeile.
Beispiel:
// Open the database Table1.Open;
Einzeilige Kommentare können dem Code, den sie referenzieren, auch folgen. Diese Kommentare, manchmal nachfolgende Kommentare genannt, erscheinen in der gleichen Zeile wie der Code, den sie beschreiben. Sie sollten mindestens durch ein Leerzeichen von dem Code, den sie beschreiben, getrennt sein. Wenn mehr als ein nachfolgender Kommentar in einem Codeblock auftritt, sollten sie alle in derselben Spalte ausgerichtet sein.
Beispiel:
if (not IsVisible) then Exit; // nothing to do Inc(StrLength); // reserve space for null terminator
Vermeiden Sie es, jede Zeile eines ausführbaren Codes mit nachfolgenden Kommentaren zu beschreiben. Es ist gewöhnlich das Beste, die Kommentare innerhalb des Begin..End-Paares einer Methode oder Funktion auf ein Minimum zu beschränken. Längere Kommentare können als Kommentarblock vor der Methoden- oder Funktions-Deklaration erscheinen.