Code-Dokumentation:Ein Leitfaden für Anfänger🎯

In diesem Blog werfen wir einen kurzen Blick darauf, wie der Code dokumentiert wird. Bevor wir uns mit der ordnungsgemäßen Dokumentation von Code befassen, wollen wir zunächst verstehen, warum es notwendig ist, Ihren Code zu dokumentieren.

Wenn wir mehr Erfahrung im Technologiegeschäft oder in der Softwareentwicklung sammeln, werden wir feststellen, dass wir viel mehr Zeit damit verbringen, Code zu lesen, als ihn zu entwickeln. Dies kann das Lesen früherer Versionen Ihres eigenen Codes, das Auswerten der Dokumentation eines anderen in Ihrem Team oder das Analysieren von Code aus Bibliotheken von Drittanbietern und deren Beispiele umfassen.

Als Ergebnis erkennen wir, dass unser Code besser lesbar und wartbar sein sollte, um die Zeit zu verkürzen, die es braucht, um ihn zu verstehen! Wir sehen uns einige Tricks und Tipps an, die Ihnen dabei helfen, Ihren Code besser lesbar und gut dokumentiert zu machen.

1. Kommentare zu Ihrem Code hinzufügen

Der Zweck des Hinzufügens von Kommentaren zum Code besteht darin, eine verständliche Beschreibung dessen bereitzustellen, was Ihr Code tut.

Beachten Sie beim Kommentieren eines Codes Folgendes:
a. Wiederholen Sie nicht einfach, was der Code tut.
b. Beschreiben Sie warum . Warum tut der Code, was er tut? Was ist die Geschäftsannahme oder der Algorithmusschritt?
c. Formatieren Sie Ihre Kommentare für maximale Lesbarkeit. Tabulator sie richtig, lassen Sie Leerzeichen, wo nötig
d. Versuchen Sie, Tools/Erweiterungen von VS-Code zu verwenden.

einige sind GhostDoc- und JSDoc-Kommentare hinzufügen

Ich persönlich bevorzuge Add JSDoc zum Kommentieren, es ist super einfach zu bedienen.

Sehen Sie sich diesen Artikel auf MSDN zum Schreiben effektiver Kommentare an

2. Testfälle schreiben :

Die meisten Entwickler schreiben Einheitentests für ihren Code um sicherzustellen, dass der Code richtig funktioniert . Dies hilft, zukünftige Fehler zu erkennen und sich davor zu schützen.

Testfälle geben Ihnen im Wesentlichen eine Vorstellung davon, wie sich der Code verhalten sollte, und wir können sicher sein, dass dies in der Produktion keine Probleme verursachen wird.

Verwenden Sie zum Schreiben von Testfällen sprach-/frameworkspezifische Tools/Bibliotheken. Ich bevorzuge Jest für NodeJS und React. Es ist schnell und sicher und ermöglicht einfaches Mocking und Code-Coverage

3. Geben Sie eine geeignete Git-Commit-Nachricht an.

Korrekte Git-Commit-Nachrichten sind auf folgende Weise von Vorteil:
a. Es verleiht den erhobenen Pull-Requests (PRs) mehr Klarheit
b. Es ist der Schlüssel zum effektiven Debugging innerhalb eines Teams
c. Vereinfacht die Nachverfolgung einer Implementierung

Es gibt einen wunderbaren Artikel über Git-Commit-Nachrichten

Wie man eine gute Commit-Nachricht schreibt

Tipp:Fügen Sie Ihrer Git-Commit-Nachricht eine Aufgaben-/Problem-ID hinzu. Dies hilft bei der Identifizierung der genauen Funktion, die gepusht wurde, und es wird einfach, sie zu verfolgen. Und Git-Commit-Nachrichten sollten Imperativ Präsens sein

z.B. #task_id commit_message #3201 Google-Login hinzufügen

4. Pflegen Sie die richtige Readme-Datei

Es ist eine Dokumentation mit Richtlinien zur Verwendung eines Projekts. Normalerweise enthält es Anweisungen zum Installieren und Ausführen des Projekts. Eine untätige Readme sollte haben
a. Projekttitel
b. Projektbeschreibung
c. So installieren und führen Sie das Projekt aus
d. Erklärung der Ordnerstruktur und Herausforderungen
e. Bekannte Probleme und Gutschriften
f. Lizenz und Versionierung

Eine Erweiterung zum Erstellen einer erstklassigen Readme-Datei. :Markdown-Vorschau verbessert

5. Schreiben Sie einen selbst dokumentierten sauberen Code

Es gibt einen Grund, warum ich dies zum Schluss aufgehoben habe, weil ich es als den wichtigsten Punkt von allen betonen wollte.

Es gibt ein paar Dinge, die ein Entwickler immer im Hinterkopf behalten sollte, wenn er Code auf Produktionsebene schreibt:

  1. Erstellen Sie eine logische und überschaubare Ordnerstruktur (für React siehe React Project Structure Best Practices for Scalable Application )
  2. Befolgung sinnvoller Namenskonventionen für Dateien, Variablen und Funktionen im gesamten Projekt
  3. Redundanten Code vermeiden:Identifizieren Sie, welcher Code wiederholt wird, und versuchen Sie, ihn zu verallgemeinern, indem Sie variable Argumente übergeben
  4. Kommentieren:Manchmal bauen Entwickler eine wirklich komplexe Logik auf und nach ein paar Monaten wissen wir, was wir getan haben, können uns aber kaum daran erinnern, warum wir es getan haben, also ist es besser, wenn Sie einige Kommentare schreiben, wann immer es notwendig erscheint.
  5. Formatierung:Eine Möglichkeit, Ihren Code lesbarer zu machen, besteht darin, den Code zu formatieren und im gesamten Projekt denselben Konventionen/Absichten zu folgen. Ich verwende die Erweiterung prettierr zum Formatieren.
  6. Überprüfen Sie Ihren Code häufig:Wenn Sie 8-10 Stunden pro Tag codieren, versuchen Sie, 1-2 Stunden für die Überprüfung aufzuwenden, um nach Verbesserungen, Optimierungen, der Arbeit an Komplexitäten (Zeit und Raum) und der Dokumentation des Codes zu suchen Code. Dies wird Ihnen in Zukunft viel Zeit sparen und Ihnen helfen, auf viel bessere Weise zu wachsen. Ich persönlich bevorzuge dafür den Nachmittag.

Lesen Sie dieses Buch für ein besseres Verständnis von Clean Code.

Schlussfolgerung

In diesem Abschnitt haben wir uns angesehen, wie Sie eine Codedokumentation schreiben, die Ihnen hilft, Ihren Code besser lesbar und gut dokumentiert zu machen.

  • Kommentare zu Ihrem Code hinzufügen
  • Testfälle schreiben
  • Stellen Sie eine geeignete Git-Commit-Nachricht bereit.
  • Pflegen Sie die richtige Readme-Datei
  • Schreiben Sie einen selbst dokumentierten sauberen Code

Insgesamt gibt es viele andere Möglichkeiten, Ihren Code zu dokumentieren, verwenden Sie diejenige, die Sie für die beste halten!

Wenn hier irgendein Punkt fehlt, teilen Sie uns dies im Kommentarbereich mit.