Kommentare
- Bitte geben Sie an, welche Sprache Sie dokumentieren möchten. Die Standards und Tools variieren zwischen den Sprachen
- Beginnen Sie damit: Was sollte Ihre Software lösen / tun? Dokumentieren Sie in erster Linie die Schritte, wie das funktioniert.
- Bitte finden Sie vorhandenen Code in vorhandenen Open Source-Projekten. Bitte lesen Sie den vorhandenen Code. Dann vergleiche es mit deinem. Stellen Sie anschließend spezifische Fragen basierend auf dem gefundenen Code.
Antwort
Sie sollten dokumentieren:
- die Absicht, das Warum;
und
- was möglicherweise nicht Seien Sie offensichtlich, wie.
Warum haben Sie dieses Bit optimiert, wofür genau ist diese Verknüpfung, was ist das erwartete Ergebnis, was ist die Anforderung, der Grund dafür, dass es vorhanden ist Erstens, wohin werden diese Daten gesendet, woher erhalten Sie die Eingabe, wenn dies ein Multithreading ist, erklären Sie das Modell, wenn es eine Datenbank gibt, erklären Sie das Schema, die Links, warum …
Dokumentieren Sie nicht das Offensichtliche. In Bezug auf die Präsentation gibt es viele Möglichkeiten, dies zu tun. Ich persönlich mag Inline-Kommentare (ich bin ein älterer Programmierer und wir hatten damals keine ausgefallenen Tools – plus ich finde es einfach und unkompliziert). Wenn Sie etwas Besonderes wünschen, stellen Sie sicher, dass es nicht zu viel Zeit in Anspruch nimmt, oder Sie werden es sehr wahrscheinlich bald aufgeben.
Kommentare
- Absicht ist oft die nützlichste Sache. Ich kann mir Code ansehen und verstehen, was er tut, aber zu verstehen, warum der Entwickler es so gemacht hat, kann sehr nützlich sein.
Antwort
Lesen Sie einen Teil Ihres eigenen Codes, den Sie vor zwei oder mehr Jahren geschrieben haben.
Fragen Sie sich, welche Arten von Dingen unklar sind, und kratzen Sie sich am Kopf Diese Art von Dingen (was auch immer sie sind, sie werden für verschiedene Programmierer unterschiedlich sein) möchten Sie zuerst über jeden neuen Code, den Sie entwickeln, oder über alten Code, den Sie neu schreiben / wiederverwenden, dokumentieren. Jede Formatierung, die Ihr Verständnis verlangsamt , ändern.
Oder in 2 Jahren …
Antwort
Eine Sache, die Sie sollten include sind die Abhängigkeiten. Wenn eine Funktion auf etwas von dort drüben angewiesen ist, dann doc ument was es ist, wo da drüben ist und warum.
Antwort
Da Sie PHP verwenden, PHPDoc wäre ein guter Anfang. Sie können Ihre API-Dokumentation inline in der Quelle erstellen und dann dasselbe Format zum Schreiben von Tutorials und Benutzerdokumentationen verwenden. Sie erhalten auch eine gewisse Flexibilität hinsichtlich des Ausgabeformats.
Antwort
Ich beginne immer mit dem Schreiben von Code, indem ich zuerst meine Kommentare schreibe. Beschreiben Sie den Programmablauf, und Sie werden feststellen, was kommentiert werden muss und was nicht. Nachdem Sie mit dem Schreiben des Codes begonnen haben, verschönern Sie die Teile, die einer zusätzlichen Erläuterung bedürfen, und verfeinern die Teile, die sich selbst dokumentieren.
Nachdem jede Klasse, Funktion oder Methode abgeschlossen ist, gehe ich zurück und füge Kommentare hinzu Für einen Dokumentgenerator wie doxygen oder PHPDoc erhalten Sie die eigentliche API-Dokumentation.
Je nachdem, wer meinen Code verwendet, schreibe ich eine formale Beschreibung des Operationsdokuments in LaTeX oder Word.
Antwort
Sauerstoff deckt die meisten Sprachen ab. Sie müssen einige Zeit damit verbringen, die Syntax zu verstehen, aber das große Problem ist, was zu dokumentieren ist. Behandeln Sie jede Funktion als Black Box. Dokumentieren Sie, was rein und was raus geht. Dokumentieren Sie, welche Fehler es abfängt, ob Argumente null sein können. ob es eine Null zurückgeben kann.
Denken Sie daran, dass Sie in nur wenigen Monaten nicht herausfinden können, was zum Teufel eine Funktion tut. Sie sparen sich nur Zeit.