Zitat von
Gentleman:
Ich habe im Zuge meines Studiums die Aufgabe bekommen, eine Software zu entwicklen. Dazu soll ich eine Dokumentation schreiben, am besten so, dass auch später andere Entwickler etwas damit anfangen können.
Quellcode-Dokumentation wurde schon angesprochen.
Beachte dabei aber bitte folgendes: Versuche, keine Redundanten Informationen zu dokumentieren.
In einem 5-Zeilen Dokumentationsheader vor einer Funktion erst nochmal den Namen, den Rückgabetyp und die Parameter samt ihrem Namen aufzuführen und mit maximal 2 bis drei 3 worten zu ergänzen ist keine Dokumentation. Der Nachteil liegt auf der Hand: Änderst Du die Methode und vergisst diese 'Doku' anzupassen (Du glaubst gar nicht, wie schnell man sich sagt 'Das mach ich nachher' und macht es dann doch nicht), dann ist die Doku nicht nur ein wenig veraltet, sondern sogar falsch. Wer sich dann daran hält hat ein Problem und muss erst nachforschen.
Also wenn Doku im Quellcode, dann nur wichtige Dinge wie 'Warum' wurde das hier so gelöst.
Der beste Quellcode spricht für sich. Also anstelle von idxCtr bitteschön den Namen IndexCounter verwenden, eine Funktion nicht Person.DelAll sondern Person.DeleteRecordWithAllDependencies nennen.
Du glaubst gar nicht, wie etwas längere, treffendere Namen den Quellcode vereinfachen.
ABER: Ein anderer Entwickler lernt am besten aus Beispielen.
Wenn Du diese Software von null an entwickelst, dann gewöhne Dir gleich hierbei an, Unittests zu schreiben. (Test Driven Development ist das Stichwort).
Das hat mehrere Vorteile:
Andere Entwickler können die Tests als Beispiel nehmen. Denn hier wird die Klasse verwendet um etwas zu tun. Und wie das getan wird ist im Test schön einfach gezeigt. Eine bessere Doku für Entwickler gibt es nicht, insbesondere nicht, wenn der Test sauber benannt ist: TestDeletePerson oder TestRenamePerson. Der zweite Vorteil: Änderst Du etwas so, dass es einen Seiteneffekt hat, dann wird Dir ein fehlschlagender Test zeigen, dass so etwas passiert ist. Änderst Du etwas so, dass sich eine Methode ändert, kompiliert das 'Beispiel' nicht mehr. Das heisst, Du hast entweder etwas nicht weit genug bedacht, oder der alte Test ist durch neue Anforderungen weggefallen oder musste sich auch ändern.
Ich empfehle Dir vielleicht vorher einen Blick in das Buch 'Clean Code' von Robert C. Martin zu werfen
, da steht vieles dazu drin, wenn auch nicht auf die Dokumentation bezogen sondern allgemein über sauberen und wartbaren Quellcode.
Imho sollte sich niemand Informatiker Schimpfen dürfen, der das nicht gelesen hat
