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.
TopperHarley schrieb: > ist meiner Meinung nach der Einsatz eines VCS (Version Control System) klingt interessant. Welches VCS verwendest du? Gruß,
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.
Thread beobachten
Seitenaufteilung abschaltenBitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.