Eure favorisierte Form der Dokumentation

[BUG]

Ich sehe gerade den Ablauf in einem akademischen Projekt, wobei mir die internen Releases mit dazugehörigen Architekturdokumenten gefallen. So ein Dokument zwingt einen im Großen ab und zu ein konsistentes Bild zusammenzutragen und lesbar auszuformulieren. Ist natürlich aufwendig.

[TBx]

Für die Nachvollziehbarkeit es Codes gilt: The code is the documentation. Verstehe ich den nach einiger Zeit nicht mehr, habe ich falsche Bezeichner gewählt und korrigiere das.
Für die Hintergründe des Projektes oder auch Erķlärungen, warum welcher Weg eingeschlagen wurde, gibt es reine Textdateien, PDFs, jpgs --> auf jeden Fall nur Formate, für die es eine Vielfalt von Readern gibt.
Das fliegt dann in ein Dokumentationsverzeichnis, welches mit allem anderen im GIT landet. Für die Historie ist das GIT da, lange Unit.- oder Funktionsheader, in denen jeder Sch*** dokumentiert ist, sind mir ein Greul.
Ich scheue auch nicht davor zurück, in Kommentaren nur auf Dokumente im Dokumentationsverzeichnis zu verweisen.

[Phoenix]

Wikis haben Erfahrungsgemäß das Problem, dass sie schnell veralten. Kaum jemand denkt im Regelfall daran, wenn er etwas im Code ändert, das auch im Wiki nachzupflegen. Wir haben bei mir auf der Arbeit das gleiche Problem. Das lässt sich mit etwas Konsequenz und Checklisten (Punkt: Doku aktualisiert? Beim Ticket / Task der abzuarbeiten ist) zwar etwas eindämmen, aber nicht ganz vermeiden.

Ich persönlich bin ein Fan von guter Code-Dokumentation, bei der man auch konzeptionelle Doku zu Architektur und abläufen in der Solution als Einzelfiles mit eincheckt und dort mit pflegt. Die aktualisierte Doku ist damit nur einen weiteren Commit entfernt, und man hat alles beisammen. Aus der Doku (Kommentare im Code sowie Konzeptionelle Doku) wird beim Release dann auch gleich die technische Doku als Webseite mit gebaut, über die der gesamte Inhalt inkl. Architekturdiagrammen etc. abrufbar ist. Wir benutzen dafür DocumentX von Innovasys. Wir sind aber ja auch eine .NET Schmiede, und ich weiss nicht ob das auch mit Delphi tut.

Grundsätzlich halte ich den Ansatz, die Doku zusammen mit dem Quellcode zusammen zu versionieren, und alles in einem Checkout zu haben, aber für das beste. Bei mir vor allem deswegen, weil wir das Dokumentationstool eben auch gleich als Plug-in in der IDE haben, und wir bei der Dokumentation daher niemals einen Medienbruch haben. Dieses Unkompliziertheit, alles gleich bei der Hand zu haben, sorgt dafür das die Doku auch deutlichst besser gepflegt wird als in einer separaten Ablage (wie z.B. ein Wiki).

[Dejan Vu]

Wir dokumentieren mit Confluence. Dabei werden Architekturansätze, Codepatterns und sonstige Systemdokumentation festgehalten und gepflegt. Code ist clean, d.h. enthält die notwendigen Dokumentationen der API und wird durch Review so gehalten, das er verständlich ist.

Über Resharper sehen wir, wann sich (zumindest bei den Parametern) die ///-Doku zu sehr von der Methode unterscheidet.

Klappt. Weil wir einen Softwarearchitekten haben, dessen Hobbies u.a. Peitschen, Teeren und Federn ist.

[Luckie]

Das funktioniert nicht. Also eine externe Dokumentation. Da könne mir die Theoretiker noch so viel erzählen. Wer sucht im Wiki schon nach Antworten, wenn er den Quellcode vor sich im Editor offen hat? Und eine externe Doku hängt dem aktuellen Stand immer hinterher. Und ich habe noch keinen Kollegen getroffen, der die externe Doku pflegt. Besser aussagekräftiger Code mit sparsamen Kommentaren warum so und nicht anders.

[redox]

Zitat von Luckie:

Das funktioniert nicht. Also eine externe Dokumentation. Da könne mir die Theoretiker noch so viel erzählen. Wer sucht im Wiki schon nach Antworten, wenn er den Quellcode vor sich im Editor offen hat? Und eine externe Doku hängt dem aktuellen Stand immer hinterher. Und ich habe noch keinen Kollegen getroffen, der die externe Doku pflegt. Besser aussagekräftiger Code mit sparsamen Kommentaren warum so und nicht anders.

Jupp.

Benutzerhilfe mit http://www.helpndoc.com/de

Ansonsten RTF-Dateien (ohne Bilder, die mit WordPad angezeigt werden können) oder PDFs mit LibreOffice.


Eventuell problematische Quelltextzeilen kommmentiere ich immer mit
...// Depp
// Depp weil es mit i < 0 abschmiert, daher i := abs(i)

https://de.wikipedia.org/wiki/Depp

[Uwe Raabe]

Zitat von redox:

Eventuell problematische Quelltextzeilen kommmentiere ich immer mit
...// Depp

DEPP = Delphi Extreme Problematic Programming

[Dejan Vu]

Zitat von Luckie:

Das funktioniert nicht. Also eine externe Dokumentation.

Die Architektur ändert sich sehr selten. Und wenn, wird die Doku nachgezogen. Das funktioniert, aber es braucht einen, der hinterher ist und dafür sorgt, das die Doku nachgezogen wird.
@Mavarik: Hast Du kein VCS? Dein Code wird doch immer unleserlicher. Hättest Du ein VCS, bräuchtest Du deine Bugfixhistorie im Code nicht.

[Bernhard Geyer]

Zitat von Phoenix:

Wikis haben Erfahrungsgemäß das Problem, dass sie schnell veralten. Kaum jemand denkt im Regelfall daran, wenn er etwas im Code ändert, das auch im Wiki nachzupflegen.

Wenn Sinnvollerweise im Quellcode (Stichwort JavaDoc und Co. ) kommentiert wreden kann, wird in 2015 (fast) keiner mehr das in einem (immer veralteten) extra Dokument machen.

Zitat von Phoenix:

Ich persönlich bin ein Fan von guter Code-Dokumentation, bei der man auch konzeptionelle Doku zu Architektur und abläufen in der Solution als Einzelfiles mit eincheckt und dort mit pflegt.

Hier wirds dann aber schwieriger wenn man z.B. ein Solution als Library für andere Anwendung hat. Dann muss man bei den anderen Anwendungen welche diese Library verwenden wo dort wieder die Doku liegt. Und Hyperlinks zwischen der Dokumentation der Anwendungen und der Library sind auch schwer möglich.

Zitat von Phoenix:

Wir sind aber ja auch eine .NET Schmiede, und ich weiss nicht ob das auch mit Delphi tut.

Lösungen gibts auch für Delpi. Evtl. nicht so umfangreich.

[mm1256]

Hallo,

externe Doku mit Word hat sich nicht bewährt. Zu umständlich, schwer zu pflegen, und wenn man was sucht oder braucht war es oft nicht aktuell. Die wichtigsten (programmier-)technischen Hinweise stehen darum im Quelltext. Für globale Zusammenhänge bei mehreren Modulen und die interne Dokumentation gibt es ein kleines Selbstgestricktes (DB, ein paar indizierte Felder zum schnellen Auffinden und ein Memo mit der Doku, sowie ein DateTimeFeld und ein User-Feld welche bei einer Änderung automatisch gesetzt werden. Dann weiß man immer automatisch, wer war's) und ansonsten gilt die Devise: Die Hilfe ist die beste Dokumentation. Darum ist bei Abschluss eines dokumentationswürdigen Vorganges sofort der Eintrag im Hilfesystem (Help&Manual) vorzunehmen, denn es müssen ja, damit die kontextsensitive Hilfe funktioniert, im OI auch die Werte des HelpContext gesetzt werden.