Eure favorisierte Form der Dokumentation

[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

[hathor]

DEPPEN = Delphi Extreme Problematic Programming errors and nonsense

[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.

[Mavarik]

Alle Änderung bleiben im Quellcode...

Beispiel:

Delphi-Quellcode:

// For i:=0 to Liste.Count do 
   For k:=1 to Liste.Count-1 do // FL 10.07.15

for k:=0 {1 // AB 11.07.15} to Liste.Count-1 // 0 war doch richtig... oder

for k:=0 {1 // AB 11.07.15} to High(Liste) // 0 war doch richtig... // FL 12.07.15 besser mit High

Irgendwann habe ich angefangen auf Documentation Inside um zu stellen... Aber schwupti war es in der nächsten Delphi Version nicht mehr dabei...

[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.

[bernau]

Zitat von Mavarik:

Alle Änderung bleiben im Quellcode...

Bei mir auch.

Zitat von Dejan Vu:

@Mavarik: Hast Du kein VCS? Dein Code wird doch immer unleserlicher. Hättest Du ein VCS, bräuchtest Du deine Bugfixhistorie im Code nicht.

Änderungen im Quellcode sollen sofort in's Auge springen. Bei einem VCS (welches ich mittlerweile verwende ) müsste man erst aktiv die alte Version vergleichen.

Sollte die Kommentare allerdings den Code unleserlich machen, werden diese Kommentare entfernt, oder ich belege die Kommentare auch einem Verfallsdatum. Heist, die Kommentare werden ab dem Datum entfernt bzw. es bleibt dann nur noch ein Kommentareinzeiler mit dem Änderungsdatum, damit ich ich darauf aufmerksam gemacht werde. Dann kann ich in's VCS hinein schauen.

[Dejan Vu]

Zitat von bernau:

Änderungen im Quellcode sollen sofort in's Auge springen.

Nur frage ich mich, was das für einen Mehrwert hat. Mich interessiert es nicht, was dort *vorher* stand. Das, was jetzt dort steht, ist relevant. Na ja. OT.

[Bernhard Geyer]

Zitat von Dejan Vu:

Zitat von bernau:

Änderungen im Quellcode sollen sofort in's Auge springen.

Nur frage ich mich, was das für einen Mehrwert hat. Mich interessiert es nicht, was dort *vorher* stand. Das, was jetzt dort steht, ist relevant. Na ja. OT.

Die Geschichte einer Quellcodezeile ist auch eine art von Dokumentation. Übers CVS ist sie halt teilweise relativ umständlich/zeitverzögert abzufragen.