Ich möchte von Ihnen alle Ratschläge und Erfahrungen zum Schreiben von Kommentaren in Ihren Code hören. Wie schreibt man sie am einfachsten und informativsten? Welche Angewohnheiten haben Sie beim Kommentieren von Codeteilen? Vielleicht ein paar exotische Empfehlungen?

Ich hoffe, dass diese Frage die interessantesten Ratschläge und Empfehlungen für Kommentare enthält, von denen jeder etwas lernen kann.

OK, ich werde anfangen.

1. Normalerweise verwende ich keine /* */Kommentare, auch wenn ich viele Zeilen kommentieren muss.

   Vorteile : Code sieht optisch besser aus als wenn Sie eine solche Syntax mit einzeiligen Kommentaren mischen. Die meisten IDEs haben die Möglichkeit, ausgewählten Text zu kommentieren, und sie tun dies normalerweise mit einzeiliger Syntax.

   Nachteile : Es ist schwierig, solchen Code ohne IDE zu bearbeiten.

2. Platzieren Sie "Punkt" am Ende eines fertigen Kommentars.

   Beispielsweise:

   //Recognize wallpaper style. Here I wanted to add additional details
   int style = int.Parse(styleValue);
   //Apply style to image.
   Apply(style);
   

   Vorteile : Platzieren Sie "Punkt" nur in Kommentaren, die Sie beendet haben. Manchmal können Sie zeitliche Informationen schreiben, sodass Sie durch das Fehlen eines Punkts darauf hingewiesen werden, dass Sie zurückkehren und diesem Kommentar zusätzlichen Text hinzufügen möchten.

3. Text in den Aufzählungen ausrichten, Parameter kommentieren usw.

   Beispielsweise:

   public enum WallpaperStyle
   {
       Fill = 100,     //WallpaperStyle = "10"; TileWallpaper = "0".
       SizeToFit = 60, //WallpaperStyle = "6";  TileWallpaper = "0".
       Stretch = 20,   //WallpaperStyle = "2";  TileWallpaper = "0".
       Tile = 1,       //WallpaperStyle = "0";  TileWallpaper = "1".
       Center = 0      //WallpaperStyle = "0";  TileWallpaper = "0".
   };
   

   Vorteile : Sieht einfach besser aus und ist optisch einfacher zu finden, was Sie brauchen.

   Nachteile : Zeit zum Ausrichten und schwieriger zu bearbeiten.

4. Schreiben Sie Text in einen Kommentar, den Sie durch die Analyse von Code nicht erhalten können.

   Zum Beispiel dummer Kommentar:

   //Apply style.
   Apply(style);
   

   Vorteile : Sie haben einen klaren und kleinen Code mit nur nützlichen Informationen in Kommentaren.

Einige der folgenden Aussagen sind recht persönlich, wenn auch mit einer gewissen Begründung, und sollen auf diese Weise erfolgen.

Kommentararten

Für die kurze Version ... verwende ich Kommentare für:

• nachfolgende Kommentare, die Felder in Datenstrukturen erläutern (abgesehen davon verwende ich eigentlich keine einzeiligen Kommentare)
• außergewöhnliche oder zweckorientierte mehrzeilige Kommentare über Blöcken
• Öffentliche Benutzer- und / oder Entwicklerdokumentation, die aus der Quelle generiert wurde

Lesen Sie weiter unten die Details und (möglicherweise unklaren) Gründe.

Hinterlegte Kommentare

Je nach Sprache können einzeilige oder mehrzeilige Kommentare verwendet werden. Warum kommt es darauf an? Es ist nur ein Standardisierungsproblem. Wenn ich C-Code schreibe, bevorzuge ich standardmäßig den altmodischen ANSI C89-Code /* comments */.

Daher habe ich dies die meiste Zeit in C und manchmal (abhängig vom Stil der Codebasis) für Sprachen mit einer C-ähnlichen Syntax:

typedef struct STRUCT_NAME {
  int fieldA;                /* aligned trailing comment */
  int fieldBWithLongerName;  /* aligned trailing comment */
} TYPE_NAME;

Emacs ist nett und macht das für mich mit M-;.

Wenn die Sprache einzeilige Kommentare unterstützt und nicht C-basiert ist, bin ich eher geneigt, einzeilige Kommentare zu verwenden. Ansonsten fürchte ich, ich habe es mir jetzt angewöhnt. Was nicht unbedingt schlecht ist, da es mich zwingt, prägnant zu sein.

Mehrzeilige Kommentare

Ich bin nicht einverstanden mit Ihrem Grundsatz, einzeilige Kommentare zu verwenden, da dies optisch ansprechender ist. Ich benutze das:

/*
 * this is a multi-line comment, which needs to be used
 * for explanations, and preferably be OUTSIDE the a
 * function's or class' and provide information to developers
 * that would not belong to a generated API documentation.
 */

Oder dies (aber das mache ich nicht mehr oft, außer bei einer persönlichen Codebasis oder meistens wegen Urheberrechtsvermerken - dies ist historisch für mich und kommt aus meiner Ausbildung. Leider machen die meisten IDEs es falsch, wenn sie das automatische Format verwenden) :

/*
** this is another multi-line comment, which needs to be used
** for explanations, and preferably be OUTSIDE the a
** function's or class' and provide information to developers
** that would not belong to a generated API documentation.
*/

Wenn es wirklich sein muss, würde ich Inline-Kommentare mit dem, was ich zuvor für abschließende Kommentare erwähnt habe, abgeben, wenn es sinnvoll ist, es in einer abschließenden Position zu verwenden. Auf einem ganz besondere Rückkehr Fall, zum Beispiel, oder Dokument eines switch‚s caseAussagen (selten, ich habe keine Verwendung wechselt oft), oder wenn wir dokumentieren Zweige in einem if ... elseKontrollfluss. Wenn dies nicht der Fall ist, ist ein Kommentarblock außerhalb des Bereichs, in dem die Schritte der Funktion / Methode / des Blocks beschrieben werden, für mich sinnvoller.

Ich verwende diese sehr außergewöhnlich, außer wenn sie in einer Sprache ohne Unterstützung für Dokumentationskommentare codiert sind (siehe unten). In diesem Fall treten sie häufiger auf. Aber im Allgemeinen dient es nur dazu, Dinge zu dokumentieren, die für andere Entwickler bestimmt sind und interne Kommentare sind, die wirklich herausstechen müssen. So dokumentieren Sie beispielsweise einen obligatorischen leeren Block wie einen "erzwungenen" catchBlock:

try {
  /* you'd have real code here, not this comment */
} catch (AwaitedException e) {
  /*
   * Nothing to do here. We default to a previously set value.
   */
}

Was für mich schon hässlich ist würde ich aber unter Umständen tolerieren.

Dokumentationskommentare

Javadoc & al.

Normalerweise verwende ich sie für Methoden und Klassen, um Versionen zu dokumentieren, die ein Feature einführen (oder ändern), insbesondere wenn es sich um eine öffentliche API handelt, und um einige Beispiele bereitzustellen (mit eindeutigen Eingabe- und Ausgabefällen sowie Sonderfällen). Obwohl in einigen Fällen ein Einzelfall besser ist, um diese zu dokumentieren, sind Einzeltests nicht unbedingt für den Menschen lesbar (unabhängig davon, welches DSL-Ding Sie verwenden).

Sie nerven mich ein bisschen, Felder / Eigenschaften zu dokumentieren, da ich es vorziehe, Kommentare nachzuschlagen, und nicht alle Dokumentationsgenerierungs-Frameworks unterstützen das Nachziehen von Dokumentationskommentaren. Doxygen zum Beispiel, JavaDoc nicht, was bedeutet, dass Sie für alle Ihre Felder einen Top-Kommentar benötigen. Ich kann das jedoch überleben, da Java-Zeilen die meiste Zeit ohnehin relativ lang sind. Daher würde mich ein nachfolgender Kommentar gleichermaßen einschüchtern, wenn ich die Zeile über meine Toleranzschwelle hinaus verlängere. Wenn Javadoc jemals darüber nachdenken würde, das zu verbessern, wäre ich viel glücklicher.

Auskommentierter Code

Ich verwende einzeilig nur aus einem Grund in C-ähnlichen Sprachen (außer wenn für striktes C kompiliert wird, wo ich sie wirklich nicht verwende): um Sachen während des Codierens auszukommentieren. Die meisten IDEs müssen für einzeilige Kommentare umschalten (ausgerichtet an Einzug oder an Spalte 0), und das passt zu diesem Anwendungsfall für mich. Die Verwendung des Umschalters für mehrzeilige Kommentare (oder die Auswahl in der Mitte von Zeilen für einige IDEs) erschwert das einfache Umschalten zwischen Kommentaren und Kommentaren.

Aber da ich im SCM gegen auskommentierten Code bin, ist das normalerweise nur von kurzer Dauer, da ich auskommentierte Chunks vor dem Festschreiben löschen werde. (Lesen Sie meine Antwort auf diese Frage zu "Inline-Kommentaren und SCMs bearbeitet von" )

Kommentarstile

Normalerweise neige ich dazu zu schreiben:

• Vervollständigen Sie Sätze mit korrekter Grammatik (einschließlich Zeichensetzung) für Dokumentationskommentare, da diese später in einem API-Dokument oder sogar als Teil eines generierten Handbuchs gelesen werden sollen.
• Gut formatierte, aber lockerere Interpunktion / Großbuchstaben für mehrzeilige Kommentarblöcke
• nachgestellte Blöcke ohne Interpunktion (wegen des Leerzeichens und normalerweise, weil der Kommentar ein kurzer ist, der eher wie eine in Klammern gesetzte Aussage liest)

Ein Hinweis zu Literate Programming

Vielleicht möchten Sie sich für Literate Programming interessieren , wie in diesem Artikel von Donald Knuth vorgestellt .

Das Paradigma der gebildeten Programmierung [...] stellt eine Abkehr vom Schreiben von Programmen in der vom Computer auferlegten Weise und Reihenfolge dar und ermöglicht Programmierern stattdessen, Programme in der Reihenfolge zu entwickeln, die von der Logik und dem Fluss ihrer Gedanken verlangt wird. 2 Literarische Programme sind eine ununterbrochene Darstellung der Logik in einer gewöhnlichen menschlichen Sprache, ähnlich wie der Text eines Aufsatzes [...].

Literarische Programmierwerkzeuge werden verwendet, um zwei Darstellungen aus einer literarischen Quelldatei zu erhalten: eine, die zur weiteren Kompilierung oder Ausführung durch einen Computer geeignet ist, den "Wirr" -Code und eine, die als formatierte Dokumentation angezeigt wird, die aus der "gewebt" wird gebildete Quelle.

Als Randnotiz und Beispiel: Das JavaScript-Framework von underscore.js ist trotz der Nichteinhaltung meines Kommentierungsstils ein ziemlich gutes Beispiel für eine gut dokumentierte Codebasis und eine wohlgeformte kommentierte Quelle - obwohl es möglicherweise nicht das beste ist, das es verwendet eine API-Referenz).

Dies sind persönliche Konventionen. Ja, ich könnte komisch sein (und Sie könnten es auch sein). Es ist OK, solange Sie folgen und entsprechen Code Konventionen Ihres Teams , wenn sie mit Kollegen arbeiten, oder nicht radikal ihre Vorlieben angreifen und cohabitate schön. Es ist Teil Ihres Stils, und Sie sollten die Grenze zwischen der Entwicklung eines Kodierungsstils, der Sie als Kodierer definiert (oder als Anhänger einer Denk- oder Organisationsschule, mit der Sie eine Verbindung haben) und der Beachtung der Konvention einer Gruppe für Konsistenz finden .

Während meines Studiums wurde mir immer beigebracht, jede Codezeile und jeden Methodenkopf zu kommentieren. Es wurde so weit eingewickelt / indoktriniert, dass Sie es ohne Frage taten. Als Mitglied mehrerer Agile-Entwicklungsteams in verschiedenen Unternehmen kann ich sagen, dass ich einmal in einem blauen Mond einen Kommentar schreiben kann.

Der Grund dafür ist zweifach: Zunächst sollten wir keine langen monolithischen Methoden mehr schreiben, die 101 verschiedene Dinge tun. Die Klassen-, Methoden- und Variablennamen sollten sich selbst dokumentieren. Nehmen Sie die folgende Anmeldemethode als Beispiel.

public void Login(string username, string password)
{
    // Get the user entity
    var user = userRepository.GetUser(username);


    // Check that the user exists
    if (user == null)
    {
        throw new UserNotFoundException();
    }

    // Check that the users password matched
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }

    //Check that the users account has not expired
    if (user.Expired)
    {
        throw new UserExpiredException();
    }

    //Mark user as logged in
    ...
}

Dies kann auf etwas zurückgeführt werden, das viel besser lesbar und möglicherweise wiederverwendbar ist:

public void Login(string username, string password)
{
    var user = GetUserForUsername(username);

    CheckUsersPasswordMatched(user, password);

    CheckUserAccountNotExpired(user);

    MarkUserAsLoggedIn(user);
}

private void User GetUserForUsername(string username)
{
    var user = userRepository.GetUser(username);

    if (user == null)
    {
        throw new UserNotFoundException();
    }
    return user;
}

private void CheckUsersPasswordMatched(User user, string password)
{
    if (user.HashedPassword != GetPasswordHash(password))
    {
        throw new InvalidUsernamePasswordException();
    }
}

private void CheckUserAccountNotExpired(User user)
{
    if (user.Expired)
    {
        throw new UserExpiredException();
    }
}

An der Anmeldemethode können Sie deutlich ablesen, was gerade passiert. Sie können dies als zusätzliche Arbeit betrachten, aber Ihre Methoden sind klein und haben nur einen Job. Darüber hinaus sind die Methodennamen beschreibend, sodass keine Methodenkopfkommentare geschrieben werden müssen. Wenn Sie am Ende zu viele Methoden haben, ist dies ein Hinweis darauf, dass die verwandten Methoden in ein anderes Objekt wie einen UserAuthenticationService re-factored werden sollten. Denken Sie daran, dass ein Objekt nur einen Job haben sollte.

Zweitens muss jeder einzelne Code, den Sie schreiben, einschließlich der Kommentare, gepflegt werden. Je mehr Kommentare Sie haben, desto mehr müssen Sie pflegen. Wenn Sie eine Klasse oder Variable umbenennen, wird ein Kompilierungsfehler angezeigt. Wenn Sie jedoch die Funktionsweise eines Codeabschnitts ändern oder den Code entfernen und keine zugehörigen Kommentare aktualisieren, tritt kein Kompilierungsfehler auf, und die Kommentare hängen herum und verursachen Verwirrung .

Wenn Sie eine API schreiben, glaube ich, dass alle öffentlich zugänglichen Schnittstellen, Klassen und Aufzählungen gut geschriebene Header-Kommentare zur Dokumentation haben sollten.

Konzentrieren Sie sich weniger auf das Format als auf den Inhalt. Zum Beispiel sagen mir die Kommentare in Ihrem Beispiel nichts Neues. Sie sind schlimmer als wertlos, da sie das Lesen von Code beeinträchtigen, und Kommentare wie diese sind bestenfalls ein vager Hinweis darauf, was der ursprüngliche Programmierer dachte, als er es schrieb. Aus dem Codebeispiel kann ich ersehen, dass Sie einen Stil "apply (Style)" anwenden. Ich kann den Quellcode lesen. Ich kann deine Gedanken nicht lesen - warum tust du das? Das sollte mir der Kommentar sagen. zB eher als

//Apply style.

Apply(style);

sollte sein

// Unlike the others, this image needs to be drawn in the user-requested style apply(style);

Die meisten von uns arbeiten in Teams an vorhandenem Code, formatieren wie der Rest des Teams, wie er bereits ausgeführt wird. Konsistenz von viel wichtiger als schön.

Schreiben Sie Ihren Code so weit wie möglich so, dass Kommentare völlig überflüssig werden. Fügen Sie nur Kommentare hinzu, wenn der Code nicht so geschrieben werden kann, dass ein wichtiges Konzept offensichtlich wird.

Meine eigene Präferenz ist es, es wirklich einfach zu halten. Ich verzichte auf jede ausgefallene Formatierung. Der Hauptgrund dafür ist, dass der Quellcode meiner Meinung nach auch mit dem einfachsten Texteditor bequem bearbeitet werden kann. Ich bringe auch nie Textabschnitte hart um, sondern lasse den Editor sanft umbrechen (kein Hinzufügen von Zeilenumbrüchen).

Ich sehe oft solche Kommentare und einige Tools generieren sie automatisch so:

/** 
 * This is an example, how to waste vertical space,
 * and how to use useless asterixes.
 */

Zwei Zeilen weniger:

/** This is an example, how to spare vertical space,
    and how to avoid useless asterixes. */

IDEs und Editoren, die sich geringfügig über der Notizblockebene befinden, können Kommentare erkennen und in einer anderen Farbe drucken. Der Zeilenanfang muss nicht mit Sternchen verziert werden.

Sie sparen sogar einige Bytes, wenn Sie einen Tabulator zum Einrücken verwenden.

Wenn Sie keinen ausgeklügelten Editor verwenden, der den Kommentar in einem Grauton wiedergibt, wird die große Anzahl von Sternchen als Hervorhebung dienen und Ihre Aufmerksamkeit auf sich ziehen. Dies ist das Gegenteil der richtigen Vorgehensweise: Zurückbleiben.

Hier ist ein "Anti-Muster", das ich im gesamten Code meines Jobs gefunden habe: Die Verwendung von Kommentaren als "Änderungsprotokoll"; Dafür ist das Protokoll in Ihrem Versionskontrollsystem bestimmt. Der Code ist übersät mit Dingen wie:

// 05-24-2011 (John Doe): Changed this method to use Foo class instead of Bar

und enthält in der Regel häufig den alten Code, der auskommentiert wurde (dies ist wiederum der Sinn eines VCS-Systems, das nach dem Schreiben des neuen Codes nicht im Code enthalten sein muss). Ebenfalls zu vermeiden sind wiederholte Kommentare wie "Warum brauchen wir das?" oder noch schlimmer: "Dies sollte wahrscheinlich umbenannt werden" (da es ausgeklügelte Werkzeuge zum Umbenennen gibt, haben Sie in der Zeit, in der Sie diesen Kommentar verfasst haben, die Sache möglicherweise umbenannt). Auch hier gehe ich regelmäßig auf diese beiden Kommentare ein, und zwar im Sinne von:

// (John Doe) 05-24-2011 not sure why we are using this object?
FooBar oFooBar = Quux.GetFooBar(iFooBarID, bSomeBool);
oFooBar.DiscombobulateBaz();

// (John Doe). This method is poorly named, it's used for more 
// than just frazzling arvadents
public int FrazzleArvadent(int iArvadentID)

1. Wählen Sie ein Dokumentationssystem wie Sauerstoff und bleiben Sie dabei. Kontrollieren Sie weiterhin die vorgelegten Dokumente.
2. Versuchen Sie, sich jemanden vorzustellen, der neu in der Codebasis ist und Ihre Dokumente liest. Könnte er damit anfangen? Praktikanten sind in der Tat gut dafür, setzen Sie sich mit Ihrer vorhandenen Dokumentenbasis und einer einfachen Aufgabe an eine neue und sehen Sie, wie weit sie kommen, wenn sie stolpern, viel sicherer, als alles, was Sie ihnen gesagt haben, um sie wieder zum Laufen zu bringen, in den Dokumenten.
3. Machen Sie Dokumentationskommentare zu einem Kontrollpunkt in Ihren Überprüfungsprozessen.

Codeleser versuchen normalerweise, drei Fragen zu beantworten:

1. Was macht diese Klasse oder Funktion? Wenn das schwer zu beantworten ist, dann macht es zu viel. Code, der schwer zu dokumentieren ist, ist normalerweise einfach falsch.
2. Wie benutze ich es? Ein Beispiel mag gut genug sein.
3. Dieser Code ist überraschend. Warum hast du das getan? Die wahrscheinlichsten Antworten: Umgehen eines Fehlers in Komponenten von Drittanbietern, da sich die offensichtliche Technik als zu langsam erwiesen hat

Alles andere sollte im Code ausgedrückt werden. Wie das Schreiben von Prosa ist dies eine Kunst und erfordert viel Übung. Die einzige Möglichkeit, festzustellen, ob Ihr Code verständlich ist, besteht darin, jemanden zum Lesen zu bewegen. Wenn sie etwas nicht verstehen, erklären Sie es nicht mündlich. Verbessere den Code. Als letzten Ausweg Kommentare hinzufügen.

Wenn ich "doppelte Länge" sehe, frage ich "Was ist die Maßeinheit?" Fügen Sie keinen Kommentar hinzu. Ändern Sie den Variablennamen. Wenn ich einen Codeblock sehe und sage "Was macht das?", Füge keinen Kommentar hinzu. Extrahieren Sie eine Funktion mit einem aussagekräftigen Namen. Wenn Sie eine Funktion nicht extrahieren können, weil sie 17 Argumente benötigt, müssen Sie den Code umgestalten.