Ist es sinnvoll eine Dokumentation zu erstellen, wenn man alleine an dem Projekt arbeitet?
-
Ich glaube nicht, dass Linus Torvalds ans alleine arbeiten dachte, als er das gesagt hat.
OT-Edit: Ich hab das wohl mit einem anderen Spruch von ihm verwechselt ... hat zum Glück noch keiner gemerkt.
-
Bashar schrieb:
Ich glaube nicht, dass Linus Torvalds ans alleine arbeiten dachte, als er das gesagt hat.
Das Problem ist die Zeit. Jetzt braucht man keine Dokumentation. Aber in 5 Jahren?
Man kann natürlich immer davon ausgehen dass man den Code nie wieder anfassen muss... Aber ob das Sinn macht?
Was man natürlich nicht braucht ist eine komplette Projekt-Dokumentation. Aber die Key Elemente des Projektes sollte man zumindest kurz umrissen haben.
-
Ich finde, es kommt auf das Projekt drauf an. Wenn man ein kurzes Tool schreibt, was nur genau einmal zum Einsatz kommen soll, braucht's da natürlich keine große Dokumentation. Bei Projekten, die sich über einen größeren Zeitraum (Monate) erstrecken, wäre ein wenig Doku nicht schlecht.
Dazu gibt's ja natürlich viele verschiedene Abstufungen von Dokumentation. Manchmal reicht eine txt-Datei, in der die grobe Wirkungsweise und das Ziel des Projekts kurz erläutert werden, man kann zu jeder Klasse 2-3 Sätze schreiben oder man macht eine "volle" Doku mit allem Drum and Dran.
-
Bashar schrieb:
Ich glaube nicht, dass Linus Torvalds ans alleine arbeiten dachte, als er das gesagt hat.
Da sind aber diese Männer und Frauen anderer Meinung
Ich denke es hängt bedeutend an der Komplexität eines Projekts. Irgendwelche Trivial-Skriptchen brauchen sicher keine ausführliche Dokumentation. Aber bei Dingen, zu denen ich "Projekt" sagen würde, braucht man sowas schon eher. Und mit Tools wie doxygen ist der Aufwand doch wirklich nicht von Kommentaren zu unterscheiden. Und über Kommentare besteht ja wohl Einigkeit.
-
Shade Of Mine schrieb:
Man kann natürlich immer davon ausgehen dass man den Code nie wieder anfassen muss... Aber ob das Sinn macht?
Wenn's mehr als zweihundert Zeilen sind, ...
- mußt Du zwangsweise davon ausgehen, daß nach ganz langer Zeit ein Eingriff in den Code nötig wird. Es wird nötig sein, den Code vollständig zu verstehen.
- falls Du wenigstens kommentiert hast, wirst Du an den Stellen, an denen Du damals besonders schlau warst, Kommentare eingefügt haben, deren Humor sich Dir heute nicht mehr erschließt, besonders beliebt z.B.: // mein Umkehrtrick, hehe!
- falls Du dokumentiert hast, ist die Doku datentechnisch kaputt, die Doku stimmt mit der letzten Release nicht überein (weil Du damals ja eh noch was ändern wolltest) oder ist für Dich heute so unverständlich wie Dein Programm.
Den Rest gibt's bei Murphy
Im Ernst, ich kommentiere hauptsächlich, was eine Funktion/Modul nach außen hin tut (also das Headerfile) und komme damit auch relativ schnell in alte Projekte rein. Für mich ein brauchbarer Kompromiß zwischen Aufwand und Nutzen.
-
Wenn den Code kein anderer bearbeiten wird und man ein gutes Gedächtnis hat, dann brauch tman keine Doku. Ich kann mir das Zeug was ich gemacht hab lange merken, aber die meisten anderen anscheinend nicht.
-
minhen schrieb:
Und über Kommentare besteht ja wohl Einigkeit.
Ui, da wäre ich mir nicht so sicher. Man liest hier öfter von Leuten so Geschichten wie "guter Code braucht keine Kommentare" oder "Dokumentation lügt". Auch wenn das durchaus mal zutreffen mag, klingt es imo eher nach "ich hab keinen Bock drauf"
on-topic: Nichts.
-
Tim schrieb:
Man liest hier öfter von Leuten so Geschichten wie "guter Code braucht keine Kommentare" ...
diese meinung war mal'ne sowas wie 'ne modeerscheinung, aber ich glaube, heute denkt die allgemeinheit anders darüber. naja, wer felsenfest behauptet, er müsse niemals kommentieren, der hat bisher nur triviales zeug programmiert oder nutzt immer sehr mächtige libraries oder sowas.
-
Wenn man sich in unbekannte Projekte einarbeiten will, dann sind Kommentare das was man nur selten braucht. Die Methoden und Klassen sollten dokumentiert sein. Wobei men bei Klassen die keine einfachen standard Sachen sind, selten ne gute Beschreibung findet, die sagt wozu die Klasse im Projekt benötigt wird. Der Aufabu und die wichtigen Strukturen im Projekt sollten gut beschrieben sein, sind sie aber meistens nicht.
-
Ich finde man sollte immer alles irgendwie dokumentieren .. nicht immer groß aufwendig aber trotzdem.
Wenn ich z.b. in der arbeit ein kleines tool schreiben muss das irgendwas ausgibt usw. dann kann man sich da natürlich nach 1 jahr wieder leicht reinlesen. Aber wenn es etwas größeres ist was 2 jahre im einsatz ist und aufeinmal wird ein update gewünscht .. na da ohne eine dokumentation sich wieder reinzufinden ist nicht immer spaßig.
Aber wie man sicher rausliest kommt es dabei irgendwie auf die größe an :D!
Finde es aber nicht schlecht weil es einem einfach oft viel zeit erspart. :))
-
Heyho schrieb:
Ist es sinnvoll eine Dokumentation zu erstellen, wenn man alleine an dem Projekt arbeitet?
Nein, wozu, du kennst ja dein Projekt auch noch in 20 Jahren.
Und wenn du dir den Code nicht in und auswendig merken kannst, dann bist du ganz einfach ein schlechter Coder.
-
Heyho schrieb:
Ist es sinnvoll eine Dokumentation zu erstellen, wenn man alleine an dem Projekt arbeitet?
Nein, wozu, du kennst ja dein Projekt auch noch in 20 Jahren.
Und wenn du dir den Code nicht in und auswendig merken kannst, dann bist du ganz einfach ein schlechter Coder.
-
Heyho schrieb:
Ist es sinnvoll eine Dokumentation zu erstellen, wenn man alleine an dem Projekt arbeitet?
Nein, wozu, du kennst ja dein Projekt auch noch in 20 Jahren.
Und wenn du dir den Code nicht in und auswendig merken kannst, dann bist du ganz einfach ein schlechter Coder.
-
tija schrieb:
Wenn man sich in unbekannte Projekte einarbeiten will, dann sind Kommentare das was man nur selten braucht. Die Methoden und Klassen sollten dokumentiert sein. Wobei men bei Klassen die keine einfachen standard Sachen sind, selten ne gute Beschreibung findet, die sagt wozu die Klasse im Projekt benötigt wird. Der Aufabu und die wichtigen Strukturen im Projekt sollten gut beschrieben sein, sind sie aber meistens nicht.
Also mal 'ne Real World Story:
Eine Sache, die jetzt 13 Jahre alt ist, kam mir letztes Jahr nochmal auf den Tisch, das waren so 3500 Zeilen reiner Assembler. Das IST de facto ein fremdes Programm. Die aktualisierte Doku ist mir bei einem Umzug kaputtgegangen, der Kunde hatte sein Exemplar verloren
und was noch da war, war nur der erste Scratch, das Gerät wurde aber mehrfach umgemodelt.Ich war gottfroh, daß ich wenigstens ordentlich kommentiert hatte und kam recht flott dazu, den Code wieder zu durchschauen, was bei ASM besonders wichtig ist, sonst hat man nur 'ne Label- Wüste
.
Das Kommentierungsschema aus der Zeit habe ich für C adaptiert in die Neuzeit übernommen, denn so kann ich die Doku weitgehend aus der Kommentierung ableiten, was sich auch schon bei jüngeren (und auch den kleinen) Projekten rentiert. Die neueren UML- Ansätze gehen sogar soweit, daß aus der Doku das Programm quasi nur als Ableitung entsteht.
So modernes Zeugs habe ich (noch) nicht und kleinere Sachen dokumentiere ich nicht, wenn niemand danach verlangt. Aber gescheit kommentiert hat man die Brücke über Jahrzehnte hinweg.