Der Wert der Codedokumentation

Codedokumentation ist die Sammlung von leicht verständlichen Bildern und schriftlichen Beschreibungen, die erklären, was eine Codebasis tut und wie sie verwendet werden kann.

Es kann sich um einfache erläuternde Kommentare zu Funktionen und Blöcken oder um ein vollwertiges Entwicklerhandbuch mit vorgeschriebenen Dos-and-Don’ts, Übersichten zu jedem Teil der Anwendung und Ansätzen zu den häufigsten Arten von Codierungsaufgaben handeln.

Es ist oft am besten, ein glückliches Mittel zwischen diesen beiden Extremen zu finden, wenn Sie die bewusste Entscheidung treffen, Ihren Code zu kommentieren und die knorrigeren Bereiche einer Codebasis in einfacher Sprache zu skizzieren.

Warum Ihren Code dokumentieren?

Warum sollten Sie sich die Mühe machen, über Ihren Code zu schreiben, anstatt nur Code zu schreiben? Wäre das nicht sowieso produktiver?

Mentale Speicherpunkte

Dokumentation ist wie ein mentaler Speicherpunkt für die Zeiten, in denen Sie am Ende des Tages endlich verstehen, was los ist und nicht an Schwung verlieren möchten. Gut dokumentierter Code stellt sicher, dass Sie, wenn Sie morgen früh (oder in einigen Monaten) wieder tauchen müssen, nicht so viel Zeit in Anspruch nehmen müssen, um sich auf den neuesten Stand zu bringen.

Dokumentierter Code wird wiederverwendet

Der Unterschied zwischen einer verwendeten Bibliothek und einer nicht verwendeten Bibliothek liegt häufig in der Dokumentation.

Wer möchte eine undokumentierte Open-Source-Bibliothek verwenden oder zu einem undokumentierten Projekt beitragen? Fast niemand.

In den meisten Fällen verwenden Sie lieber eine weniger leistungsstarke Bibliothek mit Dokumenten. Warum? Weil die Dokumentation andere Informationen über eine Codebasis vermittelt. Die Entwickler glauben, dass das Projekt die Zeit und Energie wert ist, um im Klartext darüber zu schreiben, damit jeder, der interessiert sein könnte, schnell anfangen und lernen kann, wie es funktioniert und warum wichtige Entscheidungen getroffen wurden.

Ein neues, interessantes und gut dokumentiertes Projekt in Ihrer Lieblingssprache zu finden, kann sehr aufregend und unterhaltsam sein. Schauen wir uns die extreme Alternative an: Sie müssen eine undokumentierte Codebibliothek verwenden und möglicherweise zu einer scheinbar byzantinischen Codebasis beitragen… es klingt ziemlich schmerzhaft, oder?

Warum haben Sie Ihren eigenen Code nicht dokumentiert?

Das Dokumentieren von Code ist Teil des Schreibens von gutem Code

Ein Eckpfeiler von gutem Code ist die Wartbarkeit, die durch verständliche, lesbare Dokumentation erreicht wird.

Es gibt mehrere Möglichkeiten, Code zu dokumentieren:

• gute Namen für Variablen und Funktionen auswählen
• kurze Kommentare im Code hinterlassen, um zukünftigen Lesern einen Kontext zu geben
• Hinzufügen von illustrativen Bildern wie Sequenz- und Entity-Relationship-Diagrammen
• Bereitstellen von API-Dokumenten, in denen jede Klasse, Methode, jedes Argument und jeder Rückgabewert beschrieben werden
• Verwenden einer statisch typisierten Sprache wie TypeScript (types als Dokumentation)

Vergleichen Sie zwei Beispiele

Nehmen wir an, Sie erhalten einige Daten von einer Backend-API und „betreten“ sie – konvertieren sie in eine nützlichere Form für eine front-End-Benutzeroberfläche. Hier ist die erste von zwei möglichen Lösungen.

// wdgt.jsexport const converter = (w) => { wdgtHdr = { name: w.nm, id: w.id, ts: w.lastTS } wdgtDtl = { dtlId: w.dtlId, dtlName: w.dtlNm, openTS: w.oTS, closeTS: w.cTS } wdgtRev = w.revs.map((r) => { const { note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = r const rr = { assocId: prsn1Id, assoc: `${prsn1Fn} ${prsn1Ln}`, amount: amt, note: note, revTS: cTS, } return rr } return { wdgtHdr, wdgtDtl, wdgtRev }}

Der obige Code kann schmerzhaft sein. Sie können anhand des Namens sehen, dass dies eine Art Konverter ist, der w als Parameter verwendet.

Es sieht so aus, als würde es einen Header, vielleicht Details und etwas namens revs . Woher kommt Revs überhaupt? Natürlich gibt es keine Details zu den eingehenden Variablennamen note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS … oder gibt es? Ist rr kurz für returned rev? Wer kann sagen.

Schauen wir uns das zweite Beispiel an.

// widget_utils.ts// widgetConverter :: widgetRespDTO -> widgetexport const widgetConverter = (wResp: widgetRespDTO): Widget => { const widgetHeader: WidgetHeader = { name: wResp.nm, id: wResp.Id, ts: wResp.lastTS), // timestamp } const widgetDetail: WidgetDetail = { id: wResp.widgetId, name: wResp.dtlNm, openTS: wResp.oTS, // timestamp closeTS: wResp.cTS // timestamp } // is nested inside of WidgetRespDTO // .map -> const widgetRevisions: ReadonlyArray<WidgetRevision> = wResp.revs.map((wRevs: WidgetRevisionsRespDTO): WidgetRevision => { // how that other team names their variables...! const { cmt, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = wRevs const comment: string = cmt const associateId: string = prsn1Id const associateName: string = `${prsn1Fn} ${prsn1Ln}` const amount: number = amt const revisionTS: number = cTS // unix timestamp, and "closeTS" fyi return { associateId, associateName, amount, comment, revisionTS, } } return { widgetHeader, widgetDetail, widgetRevisions, }}

Wow, wie anders! Diese Funktion befindet sich in einer util -Datei, sodass die Hauptdatei bereits weniger überladen ist. Es ist auch in TypeScript anstelle von einfachem JavaScript geschrieben, so dass wir den Vorteil von Typdefinitionen haben, um uns zu helfen.

Wir konvertieren widgetRespDTOs in widgets. Obwohl verkürzt, wissen wir genau, was wResp ist. Wir erstellen eine widgetHeader und eine widgetDetail, das ist leicht zu sehen. Wir verstehen auch, was oTS und cTS sind. Wir können sagen, dass WidgetRevisionsRespDTO s innerhalb von WidgetRespDTO verschachtelt sind.

Jemand hat die eingehenden Variablen sehr freundlich umbenannt, damit jeder, der diesen Code sieht, weiß, was sie sind. Schließlich sehen wir, dass ein Widget aus dem zurückgegebenen {widgetHeader, widgetDetail, widgetRevisions} -Objekt bestehen muss, da es mit dem oben angegebenen Rückgabetyp Widget übereinstimmen muss.

Welchen Code würden Sie besser verwenden?

Wer profitiert?

Gut dokumentierter Code kommt vielen Menschen zugute:

Junior developers

Da die Dokumentation in einfacher Sprache und leicht verständlich ist, können Junior-Entwickler und neue Teammitglieder sicher in eine Codebasis springen. Dies verhindert Frustration und frühzeitiges Aufgeben einer Aufgabe, weil sie zu schnell zu kompliziert wird.

Es ist auch hilfreich für Junior-Entwickler, ihre eigene Dokumentation zu schreiben, damit sie ihren Code mit anderen teilen und ihren Code besser verstehen können.

Senior developers

Indem Sie sich die Zeit nehmen, jetzt zu dokumentieren, verbringen Senior Devs in Zukunft weniger Zeit damit, ihren Code anderen zu erklären.

Sie können auch komplexeren Code schreiben. Mit der Dokumentation in einfacher Sprache können andere sie wie eine Blackbox verwenden, ohne das Innenleben verstehen zu müssen.

Teams & Open Source Projekte

Personelle Veränderungen können ein Projekt enorm verlangsamen. Ein aktueller und gut dokumentierter Code kann als Versicherung gegen solche Verlangsamungen dienen und es den verbleibenden Teammitgliedern ermöglichen, einen Schritt zurückzutreten, den Code auf hoher Ebene zu überprüfen und über die beste Vorgehensweise für die Zukunft zu entscheiden und gegebenenfalls neue Mitarbeiter einzubinden.

Sie

Wenn Sie Code dokumentieren, müssen Sie ihn zusammenfassen. Um richtig zusammenzufassen, müssen Sie in der Lage sein, es zu verstehen und die verschiedenen Teile gleichzeitig in Ihrem Kopf zu halten. Das Schreiben oder Beitragen zur Dokumentation ist eine Abkürzung, um eine Codebasis wirklich zu verstehen, große Beiträge zu leisten und sich als großer Teil eines großartigen Teams zu fühlen.

Gute Dokumentation kann unsere Programmiererfahrung austrocknen

Als Programmierer haben Sie wahrscheinlich vom Prinzip Don’t Repeat Yourself als Schlüssel zum Schreiben von sauberem und prägnantem Code gehört. Anstatt denselben Codeblock mehrmals zu wiederholen, schreiben Sie eine Funktion, die einmal geschrieben und in Ihrer gesamten Anwendung verwendet werden kann.

Auf die gleiche Weise sollten Sie und Ihr Team nicht auf ähnliche Probleme stoßen und das Rad jedes Mal neu erfinden, wenn Sie versuchen, sie zu lösen. Haben Sie zum Beispiel jemals einen Ihrer Kollegen gehört oder gesagt:

„Agh, ich habe etwas sehr Ähnliches gelöst, aber ich erinnere mich nie, wie ich es mache, wenn es auftaucht… Ich sollte es wahrscheinlich irgendwo aufschreiben, huh?“

Sie scannen dann immer wieder dieselben Stapelüberlauf-Threads.

Ersparen Sie sich und Ihren Mitarbeitern diesen Kummer, indem Sie dem Geist des DRY-Prinzips folgen und ein Dokument schreiben, das Sie jedes Mal verwenden können, wenn das Problem auftritt! Dies hilft Ihnen und anderen in Ihrem Team, Zeit zu sparen und einfacheren, besser verwaltbaren und effizienteren Code effektiver zu schreiben.

Wie hat sich die Codedokumentation oder deren Fehlen auf Sie ausgewirkt?