Doku zu Software

[Tom]

hallo,

kann mir jemand eine kurze hilfestellung zur doku eines quellcodes geben?

folgendes: bin hobby programmier (beginner) und wüßte gerne, wie ich "gute" doku zu meinem quellcode schreibe. ein teil ist ja die "direkte" dokumentation des quellcodes. gut, gibt's da "richtlinien" was ich machen sollte und was nicht? und dann die "externe" doku. welche module was die tun usw. klingt komisch, ist es aber nicht.

leider konnte ich im internet keinerlei beispiel doku zu einer software finden, die ich als "anleitung" hernehmen könnte.


unter den geschätzten pro-linux lesern gibt es doch bestimmt ein paar kapazunder auf dem gebiet der sw entwicklung (und doku), die mir weiterhelfen könnten, oder? <img src="http://www.pl-forum.de/UltraBoard/Images/Wilk.gif" border="0" align="middle">


gruß,
Tom

[Bob Gomorrha]

Da dieser Thread noch nicht allzu gross ist, werd ich es halt mal versuchen. Bin allerdings auch nur Hobby-Programmierer.

Eine gute Dokumentation liegt meiner Meinung nach dann vor, wenn jemand, der die Sprache zwar lesen (und verstehen)kann, aber nicht unbedingt ein Hacker-Guru ist, das versteht was Du da fabriziert hast.

Also natürlich eine Readme/man-page die das Programm und dessen Features mit Beispielen erklärt. In den einzelnen Dateien selber der Hinweis, was diese macht/kann und natürlich auch eine kurze Beschreibung der Methoden/Funktionen/Algorithmen usw.

Die Namen von Variablen/Funktionen/Prozeduren etc. sollten immer recht aussagekräftig sein, also bsp. get_vehicle_speed anstatt getvspd.

Ein Buch darüber brauchst Du Dir denke ich nicht durchzulesen - zeig die Dokumentation einfach Deiner Freundin oder einem Freund. Wenn er/sie Dir auch ohne Programmierkenntnisse sagen kann, was so in etwa abläuft ist es eine gute Doku.

[Tom]

Vielen Dank für den Tip. Werd mein Werk meiner Freundin zeigen, die hat keinen Tau von programmieren, wenn die's versteht, dann samma dabei! <img src="http://www.pl-forum.de/UltraBoard/Images/Wilk.gif" border="0" align="middle">

Gibts vielleicht ein Tool, welches mir bei der Doku behilflich sein kann?


Gruß,
Tom

[jensemann]

Hi

LaTex was sonst? Im ernst, es gibt einige Projekte die helfen sollen beim dokumentieren von code, ich hab aber mit keinen von denen gearbeitet, guck am besten mal bei freshmeat, ist ja schön sortiert da findest du sicher was.

Mfg jensemann