Wie dokumentieren/definieren professionelle Entwickler Projekte?

[Maria S.]

Hi kuddlmuddl

Stellt euch vor jemand braucht in einer komplizierten Berechnung ein wichtiges, lange ausgebrütetes Zwischenergebnis wie ne Ableitung einer mehrdimensionalen Funktion oder so.
Ich finde die einzelnen Schritte und Zwischenergebnisse können dann durchaus Stück für Stück als Kommentar in der Funktion stehen.

Siehst du und das ist falsch .. jedes einzelne Zwischenergebniss kommt aus einer Funktion die im Kopf stehen hat was sie tut.
Das ganze wird mit einem FacadePattern zusammengehalten das die Komplexität der Formel für den Anwender der Klasse verschleiert.

Klar wäre soetwas übertrieben für ein $x=$a+$b; eine eigene Funktion zu schreiben. Aber das ist ja auch lesbar. Es geht darum nicht wirklich leicht zu verstehenden Code aufzubrechen und in einzelne Funktionen auszulagern so das sich der Code der in den einzelnen Funktionen steht leichter lesen lässt und wenn die Funktionen die dann dort aufgerufen werden noch sprechende Namen haben, hat man guten OOP Code der 1. leicht zu warten ist selbst für Leute die damit sonst nichts zu tun haben, als auch 2. muß sich keiner in schweren Code reinarbeiten.

Wo soll sowas eurer Meinung nach sonst hin?

Die Erklärung was da wie berechnet wird und was dabei rauskommt gehört in ein AnwendungsfallDiagramm bzw kann in einem Klassendiagramm nachvollzogen werden. Die Mathematische Erklärung gehört in eine extra Dokumentation wenn es wirklich so eine schwere Formel ist.

Und guter Code hat nichts mit erfahren zu tun sondern mit Fleiß. Man muß halt seinen eigenen Code immer und immer wieder unter verschiedenen Aspekten refaktorieren. Und da scheitert es meistens. Da machen halt die meisten ein Copy and Paste .. bevor sie drüber nachdenken was macht die Klasse/Methode, warum will ich den Code duplizieren. Was kann ich in eine eigene Klasse auslagern, kann ich eine Abstracte Klasse oder ein Interface draufsetzen das den gemeinsamen Code bündelt. Kann ich über Vererbung erreichen das der Code gekapselt ist und nicht verdoppelt. Und so weiter. Das machen halt wenige Leute. Die Leute die ich kenne machen das weil sie irgendwann gelernt haben das Kommentare, guten Code nicht ersetzen können. Und entweder haben sie das alleine herausgefunden oder aber man mußte sie beim ersten mal dazu zwingen es herauszufinden. Es ist kein leichter Weg, da er viel mehr arbeit ist als klatsch klatsch nen Kommentar drüber und hoffen der andere Versteht das. Anstatt seine eigene Klasse zu refactorieren und eventuell sogar komplett neu zu schreiben bzw in mehrer Klassen aufzubrechen. Heißt halt viel Arbeit.
Und wenn du das Prinzip verstanden hast und umsetzt kannst du mir keinen Chef zeigen der sagt das ist unnütze arbeit das bezahl ich nicht. Weil damit schneidet er sich ins eigene Bein.

Ein Projekt darf nicht den Bach runtergehen, nur weil plötzlich ein wichtiger Mensch ausfällt (überfahren wird), der als einziger den entscheidenen Mathe-kram versteht oder so. Sowas muss zumindest ansatzweise nachvollziehbar kommentiert sein, damit sich jemand anderes da reindenken kann.

Genau das kann dir mit Kommentaren passieren. Aber mit gutem Code kann jeder der die Hochsprache beherscht nachvollziehen was passiert. Zumal der Code immer aktuell ist und niemals wie ein Kommentar veraltet sein kann.

Gruß Maria.

PS: wie immer nicht bös gemeint ... hoffe das hört sich auch nicht so an

 

[kuddlmuddl]

Mir is schon klar, was du sagen willst bezogen auf "einfache" Programme und ich weiß auch, was du meinst, wenn eine gute Struktur schlecht lesbaren Code von vorn herein vermeidet.

Ich find das geht alles etwas zu sehr ins Detail.. ich wollte nur ein reales Beispiel bringen, wo eben
1) "clean-code" zu recht verletzt wird (Performancekritische Echtzeitanwendungen / Roboter / Sicherheitssysteme / Embeded Systems mit sehr wenig Ressourcen / Automatisierte Entscheidungsfindungs-KI)
2) Kommentare im Code sein müssen (extrem komplizierte Mathematik, die niemand im Team versteht und wo auch niemand die Zeit investieren müssen sollte sich das anzueignen).

Siehst du und das ist falsch .. jedes einzelne Zwischenergebniss kommt aus einer Funktion die im Kopf stehen hat was sie tut.

Und wenn es zwischen den Zwischenergebnisse wieder gemeinsame Vor-Zwischenergebnisse gibt? Berechne ich die dann in jeder deiner neuen Funktionen immer neu? (Performance leidet dann evtl zu stark?) Reiche ich die einzelnen zB >20 Objekte als Argument an jede Funkion weiter? wohl kaum.
Fasse ich sie alle zu einem neuen Typ zusammen und reiche dieses "Vor-Zwischenergebnis" an alle Funktionen weiter? Da ist es dann aber extrem schwer sprechende Variablennamen zu finden, falls die Vor-Zwischenergebnisse unterschiedliche Dinge repräsentieren bei den einzelnen Funktionen.
Oder wenn ich nicht alle Vor-Zwischenergebnis auf anhib initialisieren kann, weil einige der Berechnungen schon fertig sein müssen, bevor die anderen anfangen können (Nebenläufigkeit)?
Oder wenn die restlichen Vor-Zwischenergebnisse eh als Abfallprodukt bei einigen der Berechnungen entstehen? Dann reiche ich das Objekt umher, obwohl viele der Variablen noch nicht initialisiert sind. Auch ne schöne Fehlerquelle..

Und guter Code hat nichts mit erfahren zu tun sondern mit Fleiß

Ne... niemand noch so fleißiges schreibt ohne Erfahrung oder gute Ausbildung guten Code. (Bei den meisten reicht weder das eine noch das andere alleine)

Die Erklärung was da wie berechnet wird und was dabei rauskommt gehört in ein AnwendungsfallDiagramm bzw kann in einem Klassendiagramm nachvollzogen werden. Die Mathematische Erklärung gehört in eine extra Dokumentation wenn es wirklich so eine schwere Formel ist.

Wie gesagt.. eine externe Doku mit Code zu Code finde ich ist einen schlimmer Fehler. Eine änderung im Code, die vergessen wird in der Doku anzupassen und schon hast du ein inkonsistentes Chaos, was ohne den Fachmann niemand mehr nachvollziehen kann.
Im Sinne von Fehlersuche, wenn Ergebnisse nicht stimmen: "Ist der Code falsch, weil bei der Herleitung was anderes steht? Oder ist bei der Herleitung ein Fehler passiert, der im Code zwar schon korrigiert wurde aber wo die Herleitung nicht angepasst wurde? Oder behauptet der Entwickler in unserem Wiki nur, dass er den Bug gefixt hat, aber er hat ihn in echt nur verschlimmbessert und nun ist beides Falsch? Code & Herleitung?"
Aus genau dem gleichen Grund soll doch auch doppelter Code vermieden werden..

Aber mit gutem Code kann jeder der die Hochsprache beherscht nachvollziehen was passiert. Zumal der Code immer aktuell ist und niemals wie ein Kommentar veraltet sein kann.

Auch guter/sauberer Code kann extrem schwer lesbar sein wenn man die implementierte Mathematik einfach nicht beherrscht, weil man sich ständig fragt "warum macht er das?" auch wenn man versteht, WAS er macht

ps: Ich verstehe, dass dus nicht Bös meinst. Finde immer nur die Pauschalisierung "Keine Kommentare im Code, weil guter Code sich selbst erklärt" falsch, weil ich andere Erfahrung gemacht habe. Mir ist klar, dass ich eher Dinge meinge, die einfach kompliziert sind während du von Problemen redest, die sich durch eine vernünftige Strukturierung tatsächlich stark vereinfach ausdrücken lassen und dann tatsächlich Kommentare überflüssig sein können

 

[Maria S.]

Gut dann haben wir ja eine Aussage

Für den normalen nicht wissenschaftlichen Programmierer sollte JavaDoc, PHPDoc oder wie die normalen Klassen und Methodenköpfe auch immer heißen mögen reichen.

Ich glaube nicht das der Fragesteller wissenschaftlicher Programmierer ist.

Und wenn es zwischen den Zwischenergebnisse wieder gemeinsame Vor-Zwischenergebnisse gibt? Berechne ich die dann in jeder deiner neuen Funktionen immer neu? (Performance leidet dann evtl zu stark?) Reiche ich die einzelnen zB >20 Objekte als Argument an jede Funkion weiter? wohl kaum.

Genau dafür machen sich seit Jahren Leute gedanken über Pattern. Und mit Pattern lässt sich nun mal jedes Problem auf die eine oder andere Art lösen.

Ne... niemand noch so fleißiges schreibt ohne Erfahrung oder gute Ausbildung guten Code. (Bei den meisten reicht weder das eine noch das andere alleine)

Da geb ich dir recht. Ich hab mich da etwas schlecht ausgedrückt .. Laie meinte ich hier natürlich, das er sich schon in der Programmiersprache auskennen sollte, aber das Thema des Programms da dürfte er Laie sein und kann trotzdem den Code lesen und natürlich mit dem wachsenden Verständniss beim Codelesen sollte er ihn auch schreiben und verbessern können.

Wie gesagt.. eine externe Doku mit Code zu Code finde ich ist einen schlimmer Fehler.

Weder im Anwendungsfalldiagramm noch im Klassendiagramm noch in der Beschreibung kommen Code vor.
Wenn ich eine Klasse ändere muß ich das Klassendiagramm anpasen das gehört zu einer guten Doku dazu. Ändert sich der Anwendungsfall muß ich das Anwendungsfalldiagramm anpassen .. sollte sich die komplette Mathematische Funktion ändern muß ich auch die externe Erklärung der Formel ändern. Das hat aber nichts mit dem zu tun was im Code steht.

Auch guter/sauberer Code kann extrem schwer lesbar sein wenn man die implementierte Mathematik einfach nicht beherrscht, weil man sich ständig fragt "warum macht er das?" auch wenn man versteht, WAS er macht

Hier gebe ich dir recht. Aber wenn derjenige nicht das Verständnis dafür hat was der Code macht. Also z.B. in unserem Beispiel eine Mathematische Null dann hat er nichts am Code zu suchen. Ich lass ja auch nicht den Deutschlehrer meiner Tochter an meinen Code. Lesen kann der sicher gut aber das Verständniss fehlt.

Gruß Maria