Hallo,
ich programmiere seit etwa fünf Jahren hobbymäßig, es sind aber
teilweise auch große Projekte draus geworden. Beim Thema Dokumentation
rollten sich anfangs bei mir immer die Fingernägel, mit der Zeit kam
dann aber das "automatische" Dokumentieren, also automatisch immer
Kommentare schreiben.
Was mir immer schwer fällt, bei fremden Projekten, ist erst einmal einen
Überblick über das Projekt zu bekommen, also welche Datei hat welche
Aufgabe und was hat die so für Methoden (Bei einem 10k-Zeilen-Projekt
vielleicht nur die Aufgaben einer Datei ;). Ich habe irgendwann
angefangen, eine Markdown-Datei zu erstellen mit genau solchen Sachen.
Wie machen das professionelle Projekte?
Gruß
PS: Gibt es Tools, um automatisch Dokumentationen zu erzeugen?
Wie machen das professionelle Projekte?
Gar nicht. Inzwischen sind alle Softwarearchitekten, die ein Händchen
für Strukturen hatten, abgehauen. Die fähigen Entwicklungsleiter auch.
Versucht man den heutzutage üblichen Code zu verstehen, werden die
Schmerzen unter den aufgerollten Fingernägeln unerträglich.
Die derzeitige Strategie nachdem die Softwarearchitekten verschwunden
sind: Ein Rudel DevOps tippt so lange planlos dran rum, bis es so
aussieht, als würde das neue Feature funktionieren.
Was die eigene Dokumentation stark verbessert, ist meiner Meinung nach
der Einsatz eines VCS (Version Control System) wie z.B. git. Am Anfang
ist es sehr ungewohnt und kommt einem unfassbar komplex und unnötig
kompliziert vor. Hat man den Dreh dann aber einmal raus, will man weder
privat noch beruflich auch nur das kleinste Projekt ohne umsetzen. Der
große Vorteil ist, dass du quasi dazu gezwungen wirst deine Änderungen
zu logischen commits zusammezufassen.
Zyniker schrieb:> Gar nicht. Inzwischen sind alle Softwarearchitekten, die ein Händchen> für Strukturen hatten, abgehauen.
nur die halbe Wahrheit.
Stimmt schon: man kriegt viele Absolventen, die nicht genug Erfahrung
mit SW-Architektur haben.
Auf der anderen Seite hat man ein paar graue Eminenzen, die glauben dass
alles noch wie vor 20 Jahren läuft, dass man die genaue Funktionsweise
einer komplexen Software in ein paar Sätzen Text aufschreiben kann, dass
zwar alles Logik aber dass Alegbra wertlos ist...
Fazit: man redet nicht mehr miteinander und jeder macht irgendwas in
seiner Welt. Und "das geht so nicht" trifft auf "das hamma immer schon
so gemacht". Natürlich nimmt da, wer klug ist, die Beine in die Hand.
@TO: dein Überblick über den Code ist nur so gut wie dein Überblick über
das Problem. Verlinke Paper oder Wikipediaseiten, die einen Ansatz
beschreiben. Erkläre den Rest. z.B. in Markdown. Dann stelle die
Verbindung her zu deinen Blöcken (z.B. Dateien). Aber vorsicht: wenn du
es hier übertreibst musst du bei Änderungen zu viel pflegen. Nur so viel
wie nötig.
Code sollte selbsterklärend sein. Kommentiere nur Dinge, die nicht von
vornerein klar sind. Überleg dazu aber, welchen Wissensstand dein Leser
hat.
Tools wie Doxygen sind nett, sorgen aber auch für clutter. Überlege dir,
ob das für dich sinnvoll ist.
Wichtig: lege das Projekt nicht beiseite, bis du mit der Doku des
aktuellen Standes zufrieden bist!
Doku schrieb:> also welche Datei hat welche Aufgabe und was hat die so für Methode
Welche Methoden sagt Dir die IDE.
Aufgaben etc. muss die Benamung erkennen lassen.
Doku für SW-quellcode ist in etwa so wie für Werkzeuge oder früher
Videorekorder. Ja, muss dabei sein, aber wenn man die lesen muss, ist
was falsch gelaufen.
> dein Überblick über den Code ist nur so gut wie dein Überblick über das Problem
Ja, hier liegt der Ansatzpunkt. Softwaredoku müsste eher so aufgebaut
sein, wie die Doku im Bauwesen. Lagepläne für den groben Überblick.
Zeichnungen, auf denen man sofort sieht, was passiert, wenn man eine
Wand heraus reisst. Und Detailpläne, die Elektriker, Installateure und
Heizungsbauer selbst zusammen stellen.
> wenn du es hier übertreibst
Anscheinend wird, nachdem es einige Jahrzehnte funktioniert,
grundsätzlich immer in irgend eine Richtung übertrieben. Im Bauwesen hat
sich eine lähmende Bürokratie ausgebreitet, die nutzlose Formalitäten
ins Unendliche aufbläst.
Zyniker schrieb:>> dein Überblick über den Code ist nur so gut wie dein Überblick über das Problem>> Ja, hier liegt der Ansatzpunkt. Softwaredoku müsste eher so aufgebaut> sein, wie die Doku im Bauwesen.
Mit dem Unterschied, dass niemand ein Haus ständig umbaut. Wenn Du
Software ähnlich gut dokumentiert haben möchtest, dann müstest Du Deinem
Kunden bei Änderungen aber auch erklären, dass die Kosten doppelt so
hoch sein werden, weil die Dokumentation ja noch angepasst werden muss.
Wenn Software einigermaßen vernünftig geschrieben ist, dann kann man
irgend wann mit etwas Erfahrung die Struktur einer Software auch
erkennen, ohne das es dafür redundante Dokumentation gibt.
Zyniker schrieb:> Gar nicht. Inzwischen sind alle Softwarearchitekten, die ein Händchen> für Strukturen hatten, abgehauen. Die fähigen Entwicklungsleiter auch.> Versucht man den heutzutage üblichen Code zu verstehen, werden die> Schmerzen unter den aufgerollten Fingernägeln unerträglich.>> Die derzeitige Strategie nachdem die Softwarearchitekten verschwunden> sind: Ein Rudel DevOps tippt so lange planlos dran rum, bis es so> aussieht, als würde das neue Feature funktionieren.
Trifft, wie ich finde, den aktuellen Stand der Softwarebranche exakt.
Am wichtigsten sind inzwischen Schweinehirten geworden: Die braucht man
um die nächste Sau durch's Dorf zu treiben.
Torsten R. schrieb:> Mit dem Unterschied, dass niemand ein Haus ständig umbaut.
Du hast wenig mit Häusern zu tun, oder? Tatsächlich ist im Bauwesen der
ständige Umbau gang und gäbe. Im Verhältnis zur Nutzungsdauer vermutlich
sogar häufiger als bei Software.
Walter T. schrieb:> Torsten R. schrieb:>> Mit dem Unterschied, dass niemand ein Haus ständig umbaut.>> Du hast wenig mit Häusern zu tun, oder? Tatsächlich ist im Bauwesen der> ständige Umbau gang und gäbe. Im Verhältnis zur Nutzungsdauer vermutlich> sogar häufiger als bei Software.
Naja, ich wohne in Häusern und die wurden bis jetzt eher selten
grundsätzlich umgebaut während ich darin wohne (Und die umfangreichen
Fasadensannierung am Altbau wurden sicher ohne Rückgriff auf die
originalen Baupläne gemacht).
Ich halte Metaphern in einer fachlichen Diskusion auch nicht für
besonders hilfreich. Den dazu müsste man erst einmal darüber
übereinstimmen, dass beide Domainen über so ähnliche Prinzipien und
Mechanismen verfügen, dass sich eine Beobachtung direkt auf die andere
Domain übertragen läßt.
Völlig unabhängig von anderen Themen, könnte ich ca. 20 Jahre Erfahrung
in der Software-Entwicklung zur Diskusion beitragen. Und die sagt mir:
Software sollte so geschrieben werden, dass sie ohne viel zusätzliche
Dokumentation gelesen und verstanden werden kann. Schnittstellen sollten
dagegen sehr gut und sehr ausführlich beschrieben werden.
Ist das hier ein Maurerforum?
Die Wahrheit liegt im code :)
Versionskontrolle ist cool und hilft über die Zeit den Verlauf halbwegs
nachvollziehbar zu haben,
und ist zwingend wenn viel Entwickler gemeinsam werkeln.
UML Diagramme sind für einige Teilaufgaben hilfreich.
Torsten R. schrieb:> Und die sagt mir:> Software sollte so geschrieben werden, dass sie ohne viel zusätzliche> Dokumentation gelesen und verstanden werden kann. Schnittstellen sollten> dagegen sehr gut und sehr ausführlich beschrieben werden.
Jack W. Reeves hat es 1992 schon auf den Punkt gebracht:
https://www.developerdotstar.com/mag/articles/reeves_design.html
Der Quellcode ist das Design.
Und im Gegensatz zu Schaltplänen, technischen Zeichnungen oder Bauplänen
wird das Produkt (die SW für einen Prozessor) mit nahezu 0 Kosten
erzeugt und reproduziert, im Gegensatz zu Leiterplatte, Getriebe oder
Haus.
Alles was parallel an Kommentaren, Tests, Dokumenten existiert, ist im
besten falle redundant und erklärend, aber ganz sicher nicht Teil des
Designs.
