mikrocontroller.net

Forum: PC-Programmierung Code Dokumentation


Autor: Doku (Gast)
Datum:

Bewertung
1 lesenswert
nicht lesenswert
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?

Autor: T.roll (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert

Autor: Zyniker (Gast)
Datum:

Bewertung
3 lesenswert
nicht lesenswert
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.

Autor: TopperHarley (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.

Autor: Al3ko -. (al3ko)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
TopperHarley schrieb:
> ist meiner Meinung nach der Einsatz eines VCS (Version Control System)

klingt interessant. Welches VCS verwendest du?

Gruß,

Autor: Adalbert Brumm (Gast)
Datum:

Bewertung
-1 lesenswert
nicht lesenswert
Al3ko -. schrieb:
> klingt interessant. Welches VCS verwendest du?

Gitea natürlich.

Autor: A. S. (rava)
Datum:

Bewertung
3 lesenswert
nicht lesenswert
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!

Autor: A. S. (achs)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.

Autor: Zyniker (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
> 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.

Autor: Torsten R. (Firma: robitzki.de) (torstenrobitzki)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.

Autor: Michael B. (laberkopp)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.

Autor: Walter T. (nicolas)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.

Autor: Torsten R. (Firma: robitzki.de) (torstenrobitzki)
Datum:

Bewertung
1 lesenswert
nicht lesenswert
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.

Autor: NichtWichtig (Gast)
Datum:

Bewertung
2 lesenswert
nicht lesenswert
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.

Autor: A. S. (achs)
Datum:

Bewertung
1 lesenswert
nicht lesenswert
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.

Antwort schreiben

Die Angabe einer E-Mail-Adresse ist freiwillig. Wenn Sie automatisch per E-Mail über Antworten auf Ihren Beitrag informiert werden möchten, melden Sie sich bitte an.

Wichtige Regeln - erst lesen, dann posten!

  • Groß- und Kleinschreibung verwenden
  • Längeren Sourcecode nicht im Text einfügen, sondern als Dateianhang

Formatierung (mehr Informationen...)

  • [c]C-Code[/c]
  • [avrasm]AVR-Assembler-Code[/avrasm]
  • [code]Code in anderen Sprachen, ASCII-Zeichnungen[/code]
  • [math]Formel in LaTeX-Syntax[/math]
  • [[Titel]] - Link zu Artikel
  • Verweis auf anderen Beitrag einfügen: Rechtsklick auf Beitragstitel,
    "Adresse kopieren", und in den Text einfügen




Bild automatisch verkleinern, falls nötig
Bitte das JPG-Format nur für Fotos und Scans verwenden!
Zeichnungen und Screenshots im PNG- oder
GIF-Format hochladen. Siehe Bildformate.

Mit dem Abschicken bestätigst du, die Nutzungsbedingungen anzuerkennen.