Ich möchte meinen Code so dokumentieren, dass er mindestens Monate später gelesen und durchsucht werden muss.

Ich weiß, dass es verschiedene Arten von Dokumentation gibt (im Quellcode und außerhalb, Sequenzdiagramme usw.).

Ich möchte nur wissen, wie ich meinen Code effizient dokumentieren kann, damit ich nach einigen Monaten weniger Zeit für das Lesen des Codes und das Verstehen des Codeflusses aufwenden muss.

Ich muss zugeben, dass ich mit einigen Dingen, die in den anderen Antworten empfohlen wurden, nicht einverstanden bin, also werfe ich meine zwei Cent.

Bemerkungen

Die Dokumentation ist für Fremde, die Ihren Code lesen, äußerst hilfreich. Normalerweise sind viele Dinge nicht ausführlich genug, um sofort gelesen und verstanden zu werden, und Sie sollten dann erklären, was Sie tun.

Bearbeiten : Die Diskussion im Kommentarbereich hat auf etwas Richtiges hingewiesen - Überkommentierung wird normalerweise durchgeführt, wenn fehlerhafter Code geschrieben wird.

Das Kommentieren Ihrer Arbeit sollte präzise und minimal sein, aber meiner Meinung nach sollte es definitiv vorhanden sein. Mindestens ein Kommentar für jeweils 15 Codezeilen. Fügen Sie zum Beispiel über den Code-Blöcken eine Zeile hinzu, die beschreibt, was Sie tun:

def login(username: str, password: str, create_session: bool = True):

    # Filter the user we need from the database
    hash = md5(password)
    users = db.table("users", db_entities.USER)
    results = [x for x in users.query(lambda c: c.get("username") == username and c.get("password_hash") == hash)]


    if len(results) == 0:
        return None, None
    else:
        # Create a login session record in the database.
        if create_session:
            sessions = db.table("sessions", db_entities.SESSION)
            ses = sessions.new()
            ses.set("username", username) \
                .set("expiery", 31536000 + time.time())
            sessions.update(ses)
            return results[0], ses
        else:
            return results[0], None

Minimale Kommentare, die erklären, warum und was Sie tun, sind im gesamten Code sehr hilfreich. Ich bin mit der Antwort, die besagt, nicht einverstanden

Wenn ich auf Code stoße, der Kommentare enthält, bereite ich mich auf das Schlimmste vor: Der Code ist wahrscheinlich schlecht, und um ehrlich zu sein, sind die Kommentare wahrscheinlich auch schlecht.

Sehr oft wird anmutig guter Code dokumentiert. Es ist wahr, dass schlechte Programmierer ihre Dokumentation wie "Okay, mein Code ist schlecht, fügen wir ein paar Sätze hinzu, um es klarer zu machen" sehen.

Ja, und obwohl dies ziemlich häufig vorkommt, ist es auch richtig, dass gute Programmierer, die sauberen Code schreiben, sicherstellen möchten, dass sie zu ihrem Code zurückkehren und verstehen, warum sich ihre Funktion so verhalten soll oder warum sie das brauchten Leitung, die etwas redundant wirkt, etc ...

Ja, Kommentare, die offensichtliche Dinge erklären, Kommentare, die unklar sind, Kommentare, die nur zusammengestellt wurden, um sicherzustellen, dass "dieser Code dokumentiert ist, ja, was auch immer", Code-Geruch ist. Sie erschweren und irritieren das Lesen des Codes. (Ein Beispiel unten hinzufügen)

# Logging into Gmail when the module is imported
_client = login()
def get_client():
    global _client
    return _client

Beispielerklärung: "Keine Scheiße, Sherlock. _client = login()Meldet sich beim Mail-Dienst an? OMG!"

login()Zur Verdeutlichung: Die Methode hat keinen Bezug zur login()Methode aus dem obigen Beispiel.

Aber Kommentare, die den Standards entsprechen, das Warum und Nicht-Wie erklären und die richtigen Fragen beantworten , sind sehr, sehr, sehr hilfreich.

Inline-Kommentare

Eine Sache, die Sie NICHT tun sollten (und wenn ich das größer schreiben könnte, würde ich es tun), ist, Ihre Kommentare in die gleiche Codezeile zu schreiben. Es macht Kommentare sehr zeilenspezifisch, was den Zweck des Kommentierens Ihres Codes völlig verfehlt.

Zum Beispiel schlechte Inline-Kommentare:

outer = MIMEText(details["message"]) # Constructing a new MIMEText object
outer["To"] = details["to"] # Setting message recipient
outer["From"] = "xAI No-Reply" # Setting message sender
outer["Subject"] = details["subject"] # Setting message subject
outer.preamble = "You will not see this in a MIME-aware mail reader.\n" # I don't know what I'm doing here, I copied this from SO.
msg = outer.as_string() # Getting the string of the message
_client = details["client"] # Assigning the client
_client.sendmail(SENDER, details["to"], msg) # Sending the mail

Es wäre viel einfacher, diesen Code zu lesen und zu verstehen, ohne die Kommentare, die ihn unübersichtlich und unleserlich machen.

Stattdessen sollten Kommentare in Ihrem Code über den Codeblöcken platziert werden und die wichtigen Fragen beantworten, die beim Lesen des Codeblocks auftreten können.

# Constructing the email object with the values 
# we received from the parameter of send_mail(details)
outer = MIMEText(details["message"])
outer["To"] = details["to"]
outer["From"] = "xAI No-Reply"
outer["Subject"] = details["subject"]
outer.preamble = "You will not see this in a MIME-aware mail reader.\n"
msg = outer.as_string()

# Sending the mail using the global client (obtained using login())
_client = details["client"]
_client.sendmail(SENDER, details["to"], msg)

Viel klarer, oder? Jetzt wissen Sie auch, dass Sie die login()Funktion verwenden und die Parameter für send_mail()alles bereitstellen müssen, was Sie verwendet haben. Hilft ein bisschen, aber eins fehlt noch.

Funktionsdokumentation

Wurde viel diskutiert. Sie sollten Ihren Lesern immer mitteilen, worum es in Ihrer Funktion geht, warum und was sie tut. Wie es das macht, das gehört nicht zur Dokumentation, sondern vielleicht zu Fußnoten der Funktion.

Sie sollten klar beschreiben, was Sie von Ihren Parametern erwarten und ob sie mit einer bestimmten Methode abgerufen / erstellt werden sollen. Sie müssen angeben, was Ihre Funktion zurückgeben soll, wie sie verwendet wird usw.

Auch dies ist meine Meinung und Methodik beim Schreiben meines Codes. Nicht nur diese, sondern auch einige der Dinge, bei denen ich den anderen Antworten nicht zustimmen konnte. Oh, und natürlich lesen nicht nur die Kommentare Ihren Code aus, sondern auch Ihren Code selbst. Schreiben Sie sauberen Code, verständlich und wartbar . Denk beim Programmieren an dein zukünftiges Ich ;-)

IMO Die beste Dokumentation ist die Dokumentation, die Sie eigentlich nicht benötigen. Ich hasse es auch, Dokumente und Kommentare zu schreiben.

Mit dem Gesagten:

• Wählen Sie lesbare und sprechende Namen. Nicht benutzen n, sondern numberOfItemsFoundzum Beispiel.
• Scheuen Sie sich nicht, Teile einer Berechnung in einer konstanten Variablen zu speichern, anstatt alles in eine Zeile zu schreiben.
• Verschieben Sie Teilaufgaben aus Zweigen in ihre eigenen (Inline-) Funktionen, wenn Sie sie wiederverwenden oder die übergeordnete Funktion zu langwierig wird.
• Seien Sie aufwändiger und optimieren Sie den Code nur dort, wo er wirklich benötigt wird.

Behandle deinen Code als Dokumentation

Ihr Code ist Ihre primäre Dokumentation. Es beschreibt genau, was die resultierende App, Bibliothek oder was auch immer tatsächlich tut. Jeder Versuch, das Verständnis dieses Codes zu beschleunigen, muss mit dem Code selbst beginnen.

Es wird viel darüber geschrieben, wie man lesbaren Code schreibt, aber einige der wichtigsten Punkte sind:

• Verlassen Sie sich nicht auf Kommentare, um schlechten Code zu erklären, den Code zu verbessern und die Kommentare loszuwerden.
• kurze fokussierte Funktionen, Methoden, Klassen usw. schreiben,
• Verwenden Sie kontextbezogene Namen (z. B. neignet sich für eine Schleife, längere beschreibende Namen sind für Elemente mit größerem Umfang erforderlich).
• Funktionsnamen wie Kommentare behandeln, z. B. nicht UpdtTblmit einem Kommentar verwenden, der erklärt, dass die Tabelle mit den angegebenen Regeln aktualisiert wird, wenn UpdateTableContentsWithSuppliedRulessie als Name verwendet werden können.
• Veränderbarkeit vermeiden. Jedes Mal, wenn Sie den Inhalt einer Variablen ändern, erhöht sich die Komplexität des Codes. Weisen Sie diesen neuen Wert nach Möglichkeit einer neuen Variablen (mit gutem Namen) zu.
• Schließlich und vor allem vermeiden Sie "cleveren" Code. Der einzige wirklich clevere Code ist Code, der einfach zu lesen ist. Wenn Sie ein komplexes Stück Code schreiben und sich denken "Wow, bin ich nicht schlau hier?", Lautet die Antwort fast garantiert "Nein, sind Sie nicht".

Werden Sie besser darin, Code zu lesen

Das Lesen von Code, unabhängig davon, wie einfach er ist, ist eine erlernte Fähigkeit. Niemand kann natürlich gut Code lesen. Es braucht Übung; viel Übung. Gehen Sie zum Beispiel zu Github oder was auch immer und lesen Sie den Code der Bibliotheken, die Sie verwenden, anstatt nur diese Bibliotheken zu verwenden. Finde Code zum Lesen und lese ihn.

Kommentare sind ein Codegeruch

Erst dann kommen wir zu anderen Dokumentationen. Vermeiden Sie erstens, wie bereits erwähnt, Kommentare. Wenn ich auf Code stoße, der Kommentare enthält, bereite ich mich auf das Schlimmste vor: Der Code ist wahrscheinlich schlecht, und um ehrlich zu sein, sind die Kommentare wahrscheinlich auch schlecht. Es ist unwahrscheinlich, dass jemand, der nicht gut über Code kommunizieren kann, besser über die natürliche Sprache kommunizieren kann.

Beachten Sie die automatisch generierte API-Dokumentation

Beachten Sie auch die automatisch generierte API-Dokumentation. Wenn ich auf das Lesen solcher Dokumente zurückgreifen muss, liegt es daran, dass Ihr Code so schwer zu lesen ist. Machen Sie den Code noch einmal einfach und ich kann ihn direkt lesen.

Tests sind auch Dokumente

Tests sind auch Dokumentation. Behandeln Sie Ihre Unit-Tests also nicht als lästige Pflicht. Behandeln Sie sie als eine Möglichkeit, mit anderen zu kommunizieren (Ihr sechs Monate späteres Ich wird hier einbezogen), wie der Code funktioniert und wie er verwendet werden soll.

Zeichne Bilder, wenn es hilft

Wenn Sie UML mögen, dann finden Sie sich auf jeden Fall ein gutes Werkzeug und generieren Sie UML-Diagramme aus Ihrem Code. Versuchen Sie niemals, damit Code zu generieren. Als Designtool ist es nicht gut, und als Ergebnis erhalten Sie schrecklichen Code.

Haben Sie ein Dokument "1000ft" anzeigen

Zum Schluss schreiben Sie sich ein Übersichtsdokument. Was macht die App? Wie macht es das? Mit welchen anderen Systemen wird die Verbindung hergestellt? Sachen wie diese. Versuchen Sie jedoch nicht, die Codestruktur hier zu beschreiben. Lassen Sie den Code das tun. Lassen Sie sich in diesem Dokument daran erinnern, warum Sie den Code ursprünglich geschrieben haben.

Geben Sie ein Anschreiben

Sofern Sie sich nicht in einem sehr technischen Bereich befinden, geht es bei den meisten Fragen rund um den Code nicht um das „Wie“, sondern um das „Warum“ oder das „Was“.

Um zu vermeiden, dass Benutzer in Ihrem Code nachsehen müssen, müssen Sie eine kurze Beschreibung schreiben. Dies hat den Vorteil, dass Sie sich auf einfache Weise einen Überblick über Beschreibungen verschaffen können und dieser sehr viel leichter zugänglich ist. (Auch für Leute, die den Code nicht sehen wollen / dürfen).

Selbst wenn die Leute technisch sind, sollte das Anschreiben Hinweise geben, wo sie etwas suchen sollten.

Einfache extrem minimalistische Punkte:

1. Einführung, warum existiert dieser Code (Basis)?
2. Welche Funktion erfüllt die Code-Teilmenge?
3. Wo ist der Code (z. B. Skriptname)

Beispiel

1. Diese Skripte zeichnen StackOverflow und Upvotes-Antworten von Dennis Jaheruddin auf
2. ein. Dieses Skript ist für das Parsen des HTML-Codes verantwortlich und analysiert, ob es sich um den richtigen Benutzer handelt
3. ein. Das Skript finden Sie unter: ScrapeAndVote / RecognizeDennis.scr

Der größte Geschwindigkeitsgewinn entsteht normalerweise durch das Erstellen separater Commits, die jeweils einen Zwischenschritt darstellen, der kompiliert und funktioniert.

Wenn ich also einen neuen Parameter in eine Funktion einführen muss, um ein bestimmtes Feature zu implementieren, gibt es ein Commit, das nichts anderes tut, als den Parameter in die Deklaration, in die Definition und an alle Aufrufstellen einzufügen. Mit dem nächsten Commit wird die Funktionalität eingeführt, und mit dem dritten Commit werden die Aufrufsites aktualisiert, die die neue Funktion verwenden.

Dies ist leicht zu überprüfen, da die rein mechanischen Änderungen schnell überblickt werden können und dann aus dem Weg gehen.

Wenn Sie den Code neu formatieren, sollte dies immer ein separates Commit sein.

Obwohl die vorhandenen Antworten ein oder zwei offensichtliche Unstimmigkeiten aufweisen, werde ich versuchen, die üblichen Ratschläge so zusammenzufassen, dass klar wird, woher alle kommen:

1. Schreiben Sie zunächst sauberen Code. Jede andere "Dokumentation" erledigt sich danach von selbst. Clean Code ist eine ganze Reihe von Grundsätzen, die in erster Linie zu lernen sind: Klassen mit einfacher Verantwortung, kurze Methoden, die eine Sache tun, gute Variablen- und Methodennamen, bessere Klassen- / Typennamen als diese, indem sie sich auf Metaphern konzentrieren (z. B. einen MultiButtSupporter aufrufen) soda), Unit-Tests, um Anforderungen anzuzeigen, DRY, SOLID, ein konsistentes Paradigma und so weiter.
2. Code zeigt, wie Code funktioniert. Kommentare zeigen, warum Code funktioniert. Erklären Sie zum Beispiel ein +1 mit "Verhindert einen Fehler um 1" oder eine komplizierte Formel mit "In diesem Lehrbuch oder auf dieser Webseite abgeleitet".
3. Was auch immer Sie mit Kommentaren gemacht haben, Punkt 1 oben kann dies mit sauberem Code erreichen. Sehen Sie Kommentare als Fehler / notwendige Übel oder sogar als Lügen, wenn sie mit der Zeit nicht mehr mit dem Code synchronisiert sind, da beide bearbeitet werden. Kommentare sollten schlecht geschriebenen Code nicht kompensieren. Warum sollten Kommentare mit mehr Talent oder Sorgfalt geschrieben werden als der Code?

Andererseits, wenn überhaupt, irre ich mich wahrscheinlich zu weit in die andere Richtung und verwende fast nie Kommentare. Ihre Code-Prüfer werden Sie informieren, wenn Sie das richtige Gleichgewicht für sie gefunden haben. Wenn Sie sich jedoch bewusst bemühen, den obigen 3-Punkte-Plan einzuhalten, sind Sie wahrscheinlich ohnehin nahe an ihrem Optimum.