Codedokumentation: Öffentlich vs. Nicht öffentlich?

10

Ich bin einer dieser Entwickler, die der Meinung sind, dass der geschriebene Code selbsterklärend sein und wie ein Buch gelesen werden sollte.

Bei der Entwicklung von Bibliothekscode für andere Benutzer versuche ich jedoch, so viel Dokumentation wie möglich in die Header-Dateien aufzunehmen. was die Frage aufwirft: Lohnt es sich überhaupt, nicht öffentliche Dokumentationsmethoden zu dokumentieren? Sie werden sie nicht direkt verwenden, tatsächlich können sie es nicht. Zur gleichen Zeit, wenn ich den Rohcode verteile (wenn auch widerstrebend), sind diese nicht öffentlichen Methoden sichtbar und müssen möglicherweise erklärt werden.

Suchen Sie nur nach Standards und Praktiken, die Sie alle auf Ihren Reisen sehen oder anwenden.

c++ documentation Casey
quelle

Antworten:

12

Ich würde niemals in Betracht ziehen, die Dokumentation für Interna wegzulassen, nur weil ein "Endbenutzer" sie nicht verwendet. Die Codepflege ist mehr als genug Grund, Dokumentationskommentare für alle Komponenten aufzunehmen, insbesondere für Interna, die in der Regel der komplexeste (und sich häufig ändernde) Teil sind.

Es kann jedoch ein gültiger Fall vorliegen, dass sie auf den Nicht-Header-Quellcode beschränkt (und nicht öffentlich dokumentiert) werden, um die Abstraktion aufrechtzuerhalten.

Das ist alles ziemlich subjektiv, wohlgemerkt.

Leichtigkeitsrennen im Orbit
quelle
1
Ich stimme zu, wenn Sie möchten, dass der Code beibehalten wird, müssen Sie so deutlich wie möglich machen, was jeder Teil davon zu erreichen versucht, ob er privat ist oder nicht. Ich bin sicher, Sie können wählen, ob Sie die private Dokumentation in Doxygen generieren möchten oder nicht.
3

Ok, ich füge dem Bild aus Gründen der Abwechslung auch meine Art zu kommentieren / dokumentieren hinzu. Grund dafür ist, dass ich es vermeide, Funktionen oder Elementfunktionen zu beschreiben, die nur dort im Header deklariert sind. Einerseits befürchte ich, dem Header zu viel Rauschen hinzuzufügen. Andererseits ist die Dokumentation zusammen mit der Definition für den Betreuer einfacher zu finden. Doxygen ist das egal und kann bei Bedarf Privaten herausfiltern.

In der Klassenüberschrift:

  • enthaltene Header (warum)
  • Klassendefinitionen immer (Zweck und Verantwortlichkeiten)
  • die rein virtuellen Funktionen immer (Vollvertrag)
  • Die Inline-Funktionen funktionieren nur, wenn sie selbsterklärend sind
  • andere deklarierte Typen, sofern nicht selbsterklärend
  • statische Datenelemente (warum)
  • andere Datenmitglieder, sofern nicht selbsterklärend
  • die Makros, falls vorhanden (Vertrag und warum)

Im Klassenimplementierungscode:

  • lokale Deklarationen wie im Header
  • Funktionsdefinitionen immer (vollständiger Vertrag)
  • Mitgliedsfunktionsdefinitionen immer (vollständiger Vertrag oder Verweis auf die Wurzel der virtuellen Überschreibung)
  • statische Variablen definiert, falls vorhanden (Zweck warum)

Im Vorlagenkopf:

  • die oben zusammengeführt und
  • geeignete / ungeeignete Typen für Vorlagenargumente und
  • wie gut die Eignung statisch erkannt wird

quelle
2

Am private:Anfang des privaten Abschnitts finden Sie alle Dokumentationen, die Benutzer benötigen sollten.

Marcelo Cantos
quelle
1

Dokumentation ist jeden Tag wert, sie hilft, Anwendungsfälle und Geschichten kurz zu erklären. Wie sehr der Code auch selbsterklärend ist, er kann das Geschäft nicht so einfach erklären wie wenige Zeilen Geschichtenerzählen. Der Code würde definitiv erfordern, dass der Benutzer der Logik folgt und zusätzlich versteht, was vor sich geht. :-) Meine 2 Cent ...

r0ast3d
quelle
OK, aber Sie sprechen nicht die Unterscheidung zwischen Dokumentation für die öffentliche API und Dokumentation für interne Abläufe an.
Leichtigkeitsrennen im Orbit
1

Bestimmt!

Dieser Code sollte sich selbst dokumentieren und ist ein Slogan, nach dem man leben muss. Ich würde jedoch so weit gehen zu sagen, dass privater Code genauso viel Dokumentation benötigt, wenn nicht sogar mehr als öffentlicher Code, da hier normalerweise die meisten Annahmen getroffen werden, nur weil der Codierer davon ausgeht, dass er im Dunkeln bleibt . Ein paar Monate später, wenn ein Fehler auf Sie zukommt, werden Sie Zeit damit verbringen, sich daran zu erinnern, was die Idee hinter dem Code war (vielleicht haben Sie selbst).

Dokumentation sollte nicht als schönes Geschenk für andere da sein. Die Dokumentation in all ihren Gesichtern (ausgewählte Variablennamen, selbstdokumentierende Klassennamen, gut organisierter Code, richtig segmentierte Methoden usw.) ist ein Geschenk für alle, die mit Ihrem Code in Kontakt kommen können, auch für Sie.

Gustavo Mori
quelle