Wie dokumentiere ich meinen Code für eine Überprüfung mit minimalem Zeitaufwand? [geschlossen]

22

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.

Hamed_gibago
quelle
42
Die beste Methode, um später weniger Zeit mit dem Lesen von Code zu verbringen, besteht darin, klareren und verständlicheren Code zu schreiben .
Mael
Die Dokumentation ist abhängig vom Ziel. Wenn Sie sich an Entwickler wenden, sind Kommentare im Code sehr nützlich. Wenn Sie sich an Analysten wenden, sind auch Diagramme der Übersicht hilfreich. Wenn Sie sich an ein technisch versiertes Publikum wenden, erstellen Sie eine Bedienungsanleitung.
Laiv
@Laiv Nun, angesichts eines Entwicklers meines eigenen Codes und vielleicht eines anderen Entwicklercodes.
Hamed_gibago
Das Größte ist, den Code klein zu halten. Wenn der Code, der zum Implementieren eines Elements in Ihrem Fehlerverfolgungssystem erforderlich ist, groß ist, muss Ihr Team möglicherweise lernen, wie er weiter aufgeteilt wird, damit die Menge des überprüften Codes nicht übermäßig ist.
Berin Loritsch

Antworten:

16

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 ;-)

Yotam Lachs
quelle
5
Nicht einverstanden mit einem bestimmten Beispiel - anstatt viele Kommentare in eine große Funktion zu schreiben, sollten Sie diese aus vielen kleineren Funktionen mit beschreibenden Namen zusammensetzen, die als Kommentare fungieren. Ohne das Risiko, nicht mit dem synchron zu sein, was der Code wirklich tut.
user11153
6
Endlich ein bisschen Verstand. Wenn Sie jeden Code, der einen Kommentar enthalten könnte, in eine eigene Funktion extrahieren, erhalten Sie Tausende von Funktionen, die auf Hunderte von Dateien verteilt sind.
user369450
2
Das zweite Beispiel ist schön.
Leichtigkeit Rennen mit Monica
7
Die Kommentare im zweiten Beispiel sind viel zu ausführlich. Einige von ihnen (z. B. "Haben wir etwas gefunden?") Wiederholen einfach, was der Code sagt und sollten besser entfernt werden. Zum anderen können Sie die Lesbarkeit verbessern, indem Sie die Loop-Bedingung umgestalten (stream.is_empty ()) oder die Prüfung auf accept_literals nach außen verschieben.
Frax
3
@cpburnz, "Ich musste zu viele Legacy-Projekte und Bibliotheken von Drittanbietern ohne Code-Kommentare durchsuchen, um Kommentare zu schätzen, die erklären, was passiert und warum". Genau mein Punkt die ganze Zeit: Kommentare sind da, um Mistcode zu erklären. Da die Frage lautet "Wie schreibe ich Code, der so einfach zu lesen ist?", Ist diese Antwort eindeutig falsch, da sie sich auf das Schreiben von Kommentaren konzentriert, um schlechten Code zu erklären, anstatt an erster Stelle guten Code zu schreiben.
David Arno
55

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.
Mario
quelle
19
Hier ist eine gute Metrik für die Dokumentation (obligatorischer Link).
Neil
4
Dies sollte auch auf der Liste stehen: Erklären Sie im Code, warum Sie Dinge tun, die Sie tun.
t3chb0t
2
+1 für den letzten Aufzählungspunkt, da vorzeitige Optimierung (in 97% der
Fälle
4
numberOfItemsFoundist aber ziemlich ausführlich; zu wortreich ist auch ein Thema.
Matthieu M.
6
@MatthieuM., Selten ist "zu ausführlich" ein Problem mit Namen im Code. Zu knapp oder kryptisch ist jedoch ein weit verbreitetes Problem.
David Arno
25

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.

David Arno
quelle
14
Ich stimme allen Ihren Ausführungen zu, mit der Ausnahme, dass Kommentare ihren Platz haben. Obwohl Kommentare wie meiner Meinung nach sinnlos sind add 1 to i, sollten sie erklären, warum der Code das tut, was er tut. Zum Beispiel kann der Code if (!something.Exists()) {...}kann einen Kommentar wie verwenden: // something exists only when (explanation of the broader scenario).
Jonathan
16
Wir haben alle gesehen, // increment x x++;dass viele Kommentare nichts nützen, aber es ist falsch, das Baby mit dem Badewasser hinauszuwerfen und zu erklären, dass Kommentare immer schlecht sind. Zum Beispiel Kommentare des Formulars // this case should never happen because xyz throw exception "unreachable".
Angrydust
7
Sehr schöne Liste. Aber wie bei Jonathan. Ich bin mit den Kommentaren nicht einverstanden. Manchmal müssen Sie jedoch Fehler in Frameworks von Drittanbietern berücksichtigen. Obwohl dies in eine eigene Funktion überarbeitet werden kann, ist es dennoch hilfreich, eine kurze Beschreibung zu hinterlassen, warum die Problemumgehung (Fehlernummer oder Fehlername / Fehlerbeschreibung) erforderlich ist.
magu_
16
@DavidArno Aber Sie können das nicht für einen Kommentar tun, der erklärt, warum etwas nicht getan wurde. Wie //XXX: Not using straight-forward method Foo here because .... Solche Kommentare können immens wertvoll sein, sind jedoch aus offensichtlichen Gründen nicht mit Code zu übermitteln.
CMASTER
7
Ich mag es noch dramatischer: Jeder Kommentar ist ein Fehler, sich im Code gut auszudrücken . Zum Beispiel habe ich einen 4-zeiligen Kommentar in einer Methode, der die Problemumgehung für einen Fehler eines Drittanbieters erklärt. Ich habe es nicht geschafft, dies in Code auszudrücken, also steht es in einem Kommentar . Ich würde sagen, es hat die Lesbarkeit erschwert, da ich bezweifle, dass jemand gerne horizontal scrollen würde, um einen sehr langen und sehr beschreibenden Methodennamen zu lesen . "Kommentare sind ein Codegeruch" - ja, aber wir müssen uns daran erinnern, dass nicht alles, was riecht, Scheiße ist.
R. Schmitz
5

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
Dennis Jaheruddin
quelle
1

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.

Simon Richter
quelle
1

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.

JG
quelle
2
Wie unterscheidet sich ein Kommentar "Verhindert ein Aus um 1 Fehler" von einem Kommentar, der besagt, dass "+1 kein Tippfehler ist" oder "Ich bin mir nicht bewusst, dass ein Fehler in meinem Programm ein Aus ist"? (Nützliche Kommentare beziehen sich im Allgemeinen auf etwas, das größer als +1 im Quellcode ist, oder auf etwas, das außerhalb des Quellcodes liegt.) So bleibt "abgeleitet in diesem Lehrbuch oder auf dieser Webseite" immer noch ein gültiges und wirklich gutes Beispiel in Punkt 2. Dann scheint Ihr Punkt Nr. 3 darauf hinzudeuten, dass Sie in der Lage sein könnten, "abgeleitet in diesem Lehrbuch oder auf dieser Webseite" auszudrücken, indem Sie ausreichend sauberen Code ohne Kommentare verwenden. Wow, ich würde das gerne in Aktion sehen.
Jirka Hanika
@JirkaHanika Vielleicht war Off-by-One ein schlechtes Beispiel. In Bezug auf 3 meinte ich "jeder darf" und nicht "vielleicht jeder". Nein, ich glaube nicht, dass Code allein solche Dinge klarstellen kann. (Nun, Sie könnten versuchen, gaussianFromThisTextbookNamesApproximation als Variablennamen, aber das ist eine schlechte Idee!)
JG