Änderungsdokumentation

Barf
Developer
Beiträge: 1475
Registriert: Dienstag 4. Februar 2003, 22:02

Änderungsdokumentation

Beitrag von Barf »

In einem Feature Request Thread schreibt rasc:
(einige schreiben noch nichtmal ein Kommentar fuer ihre Aenderungen)
(ich möchte den Thread nicht zweckentfremden, deswegen öffne ich eine neue in "Developer").

Ich bin der Meinung, das Änderungsdokumentation wichtig ist, aber nicht als Kommentaren in Code gehört. Änderungsdokumentation gehört in dem Versionsmanagementsystem, hier CVS. (Alternativ in einem ChangeLog.) Änderungsdokumentationskommentare in Code macht den Code unübersichtliger. Kommentare soll dazu dienen, den aktuellen Zustand des Codes zu beschreiben. Ähnlicherweise soll nicht mehr benötigte Zeilen gelöscht werden, nicht auskommentiert. (Natürlich gibt es Ausnahmen...)

Was meint die ihr? Offensichtlich ist rasc nicht allein mit seiner Meinung.

Ich möchte betonen, dass ich in keiner fall rasc persönlich angreifen möchte, sondern ich will eine Diskussion in der Sachfrage.
Innuendo
Einsteiger
Einsteiger
Beiträge: 281
Registriert: Mittwoch 8. Dezember 2004, 21:45

Beitrag von Innuendo »

grundsätzlich find ich es gut, daß überhaupt noch wer seine freizeit opfert. dabei etwas verlangen oder fordern ist immer schwierig und wird meist mist-verstanden.
den vorschlag mehr infos/dokumentation zu den änderungen sollten imho die devs annehmen bzw sich ein bissl dazu zwingen ein paar zeilen zu ihrer arbeit zu schreiben oder wie ab und an schon passiert auf ein forum verlinken ... macht es doch im endeffekt für alle nur einfacher.

regards
innu
Metallica
Einsteiger
Einsteiger
Beiträge: 191
Registriert: Dienstag 30. Dezember 2003, 01:49

Beitrag von Metallica »

Ich würde schon ChangeLog wie bei dvbsnoop begrüssen.
gruss.
rasc
Senior Member
Beiträge: 5071
Registriert: Dienstag 18. September 2001, 00:00

Re: Änderungsdokumentation

Beitrag von rasc »

Barf hat geschrieben:
Was meint die ihr? Offensichtlich ist rasc nicht allein mit seiner Meinung.

Ich möchte betonen, dass ich in keiner fall rasc persönlich angreifen möchte, sondern ich will eine Diskussion in der Sachfrage.

Hö?

Also ich beschwere mich nur, dass der Source von einigen nicht kommentiert wird. Das ist unabhängig, ob da eine Änderung erfolgt oder ob der Code neu ist.

Ansonsten ist der CVS-Commit und das ChangeLog der richtige Platz fuer die Dokumentation der Änderung.

Die einfachste Methode waere Commits ohne ausreichenden Kommentaren wieder zu reverten... 8)
Metallica
Einsteiger
Einsteiger
Beiträge: 191
Registriert: Dienstag 30. Dezember 2003, 01:49

Re: Änderungsdokumentation

Beitrag von Metallica »

rasc hat geschrieben:Die einfachste Methode waere Commits ohne ausreichenden Kommentaren wieder zu reverten... 8)
meinst sowas ?
http://cvs.tuxbox-cvs.sourceforge.net/t ... 1&r2=1.172
;)
rasc
Senior Member
Beiträge: 5071
Registriert: Dienstag 18. September 2001, 00:00

Beitrag von rasc »

Nun, bei solchen kleinigkeiten kann das schonmal vorkommen, dass man ohne CVS-Kommentar aendert - ist aber eher als Ausnahme zu sehen (oder habe ich noch andere Commits nicht kommentiert (mal abgesehen von Folge-Commits, bei denen was vergessen oder korrigiert wurde?.
Metallica
Einsteiger
Einsteiger
Beiträge: 191
Registriert: Dienstag 30. Dezember 2003, 01:49

Beitrag von Metallica »

kA , aber ich weiss nicht wieso du es erst jetzt beklalgst ?
und ich denke die meisten haben auch so wie du gemacht.
Barf
Developer
Beiträge: 1475
Registriert: Dienstag 4. Februar 2003, 22:02

Beitrag von Barf »

Das Beispiel von Metallica zeigt auch die Unsitte, Code wegzukommentieren statt zu löschen. Fast immer unnötig (warum haben wir ein Versionmgtsystem?), macht die Code nur hässlig und unübersichtlich. (Ein IEC-norm verbietet auskommentierte code in sicherheitskritische SW, falls ich mich richtig erinnere.)

Ich will nicht diskutieren wer ferkelt und wer nicht, nur ein Problem identifizieren, das zu dem bedauerliche Zustand der Neutrino-quellen stark beigetragen hat.
rasc
Senior Member
Beiträge: 5071
Registriert: Dienstag 18. September 2001, 00:00

Beitrag von rasc »

Barf hat geschrieben:Das Beispiel von Metallica zeigt auch die Unsitte, Code wegzukommentieren statt zu löschen. Fast immer unnötig (warum haben wir ein Versionmgtsystem?), macht die Code nur hässlig und unübersichtlich. (Ein IEC-norm verbietet auskommentierte code in sicherheitskritische SW, falls ich mich richtig erinnere.)

Das ist eine Philosophie-Frage...

Ich kommentiere erst weg und wenn sich der neue Code als stabil erwiesen hat, wird der alte auch gelöscht. So hat man beim Bug-Tracking immer noch Zugriff auf den alten Code, ohne sich durch diffs durchquälen zu muessen.

Und ja, manchmal lasse ich alten Code als mögl. Alternative bewusst stehen. Das macht Neutrino aber nicht kompliziert - da wuesste ich einen ganzen Stapel andere Argumente...


Ein Glück dass Neutrino nicht wirklich sicherheitskritisch ist, sonst wuerde auch noch jemand UML oder ClearCase oder sonstwas fordern...


Mir persönlich sind auch die CVS-Commits-Texte egal. Die nützen nix, wenn man die eigenen Gedankensprünge im Source nicht zumindest minimal kommentiert - insbesondere weil es heute schon reichlich Seiteneffekte gibt, die man im einzlnen Source-Modul direkt nicht erkennen kann.
Günther
Developer
Beiträge: 587
Registriert: Freitag 9. September 2005, 21:48

Beitrag von Günther »

Meiner Meinung nach sollte auch kein Code nur auskommentiert werden. Allerdings, die Methode von rasc ist sicherlich OK, wenn der Code dann auch wirklich gelöscht wird. Auch das Kommentieren von Änderungen haben im Code eigentlich auch nichts zu suchen (das normale Kommentieren und die Funktionsdefinitionen jedoch sehr wohl).

Allerdings, wenn ich im Code meines Kollegen etwas ändere, kommentiere ich das in der Regel relativ ausführlich im Code, damit er schnell weiß, woher und warum der Code eingefügt wurde.

Neben der Änderungsdokumentation im cvs ist es meiner Erfahrung nach sehr sinnvoll, ebenfalls eine Revision-History im File-Header zu führen (Datum, Name, Änderungsnummer, Kurzbeschreibung) da der Weg über cvs oft recht umständlich ist (vor allem bei Projekten mit mehr als 1000 Files).

Vor allem denke ich aber, daß der Grund warum Software nach einiger Zeit unleserlich wird meißt daran liegt, daß zu viele Entwickler am gleichen Code (oder noch schlimmer fremden Code) rumwursteln, ohne irgendwelche Regeln zu beachten. Dazu kommt, daß nur der erste Entwickler alle Zusammenhänge seiner Software kennt. Alle Nachfolgenden verstehen meist nicht alle Kniffe des Vorgängers (10 Programmierer lösen das selbe Problem auf 10 verschieden weisen ..) und schon steigt die Gefahr von Verschlimmbesserungen.

Dagegen helfen nur strenge Coding- und Design-Regel, sowie ein starker Technical-Lead. Kostet natürlich Zeit (und Geld) funktioniert aber recht gut. Ohne jede Regeln kann zwar in kürzester Zeit Beachtliches geschaffen werden, nur die Wartung gerät meistens zur Katastrophe . :wink:

Ich bin ja noch nicht sehr lange hier aktiv, aber ich vermute, daß es bei Neutrino ähnlich war. Sprich, am Anfang war noch alles gut strukturiert und mit der Zeit (nachdem die anfänglichen Entwickler sich zurückgezogen haben) gingen die Probleme los.....

Bitte versteht das nicht als Kritik, so ist wohl der Lauf der Dinge (nicht nur bei OpenSorce sondern auch bei Firmen :wink: )
mws
Developer
Beiträge: 331
Registriert: Freitag 7. Februar 2003, 22:17

Beitrag von mws »

Neben der Änderungsdokumentation im cvs ist es meiner Erfahrung nach sehr sinnvoll, ebenfalls eine Revision-History im File-Header zu führen (Datum, Name, Änderungsnummer, Kurzbeschreibung) da der Weg über cvs oft recht umständlich ist (vor allem bei Projekten mit mehr als 1000 Files).
das liegt dann aber an den verwendeten tools.

gruss
mws
cu
mws