Registriert: Do Sep 25, 2003 15:56 Beiträge: 7804 Wohnort: Sachsen - ERZ / C
Programmiersprache: Java (, Pascal)
Also früher hab ich größere Dokupassagen im Code gehabt. Aber dank Java und Javadoc hab ich jetzt immer ne schicke Doku zur Hand. Vorallem die Javadoc einbindung in Eclipse find ich extrem hilfreich. Mit Doxygen kam ich damals bei Delphi leider nicht klar. Hab nicht eine Seite generieren können.
_________________ Blog: kevin-fleischer.de und fbaingermany.com
Beim Turbo Delphi kann man aus dem UML-Editor heraus Dokumentation erzeugen.
Habe selber "Bei den interessanten Stellen stehen 1-2 Zeilen im Code." ausgewählt. Das trifft zumindest für Hobby-Projekte (alleine) zu und ich denke darum geht es hier. Ich programmiere auch häufiger mit dem Visual Studio und dort funktioniert das mit den Kommentaren zur Dokumentation ähnlich wie bei Eclipse. Anders als bei Java erzeugt der Compiler aber nur eine XML-Datei die man dann mit verschiedenen Tools weiter bearbeiten kann um .chm, HTML oder sonstige Hilfedateien zu erzeugen. Falls eine Dokumentation nötig ist, mache ich dass dann auch über diese Kommentare.
Kommt sehr auf das Gebiet an. In manchen Units sind gar keine Kommentare, in anderen jede 2. Zeile. Je nachdem wie der Code beschaffen ist. Und wie wichtig das Projekt ist
Registriert: Mo Sep 23, 2002 19:27 Beiträge: 5812
Programmiersprache: C++
Da meine meisten Quellcodes nicht öffentlich sind kommentiere ich nur die wichtigen Stellen kurz, damit, wenn ich später nochmal an die Quellen muss, weiss wodrums geht. Ansonsten fällt Kommentierung bei mir aufgrund passend gewählter Klassen-, Prozeduren und Variablennamen weg. Ne Funktion namens "TRegion.NextRound" oder "TNation.RemoveArmy" braucht ja schon von Natur aus keinen Kommentar, besonders wenn die Bezeichner der übergebenen Variablen sinnvoll gewählt sind.
Registriert: Mi Jul 17, 2002 12:07 Beiträge: 976 Wohnort: Tübingen
Es fehlt mal wieder eine Option: "Würde gerne dokumentieren, wenn ich nicht so faul wäre"
_________________ "Du musst ein Schwein sein in dieser Welt, sangen die Prinzen, das ist so 1.0. Du musst auf YouTube zeigen, dass dir dein Schweinsein gefällt, das ist leuchtendes, echtes Web 2.0." - Hal Faber Meine Homepage: http://laboda.delphigl.com
Registriert: Sa Mai 04, 2002 19:48 Beiträge: 3827 Wohnort: Tespe (nahe Hamburg)
Bei einem kommerziellen Projekt erfolgt ausführliche Dokumentation im Quellcode UND eine Dokumentation in Textform, um die darinne vorkommenden Mechanismen näher zu erläutern. Ich denke man sollte eine gute Dokumentation so gestalten als ob das gesamte Programmierteam und das beratende Personal in zwei Flugzeugen irgendwo in der Weltgeschichte unterwegs sind und sich in der Mitte treffen. Wenn dann der Nachfolger von einem einen nicht hinterherweinen muss, war die Dokumentation ausreichend.
Privat beschränke ich mich zumeist auf eine Erläuterung von Methoden oder meist auch nur Klassen... wobei ich es ähnlich wie Sascha sehe. Vernünftige Variablen und Methodennamen sind bereits die halbe Miete. Schaut man selbst auf seinen Code und weiß 5 Monate später nicht mehr wie etwas funktioniert, liegt es nahe, dass man unglücklich strukturiert hat. (und das sei nichtmal eine Schande...)
_________________ "Light travels faster than sound. This is why some people appear bright, before you can hear them speak..."
Also ich kommentiere im normalfall per C# XML-Kommentare (schaut so ähnlich aus wie javadoc, kann auch am Ende ähnlich eingesetzt werden). Das klappt im normalfall auch ganz gut, wenn man aber wirklich mal etwas deutlich komplizierteres macht, dann kann schon mal sein, daß sich irgendwo eine generelle erklärung findet, was da intern genau abgeht - besonders bei etwas wilderen tricks, abstrakte einführungen oder auch bei einigen Dingen die beim multiprogramming auftauchen, sind gelegentlich ausführlichere klärende Worte sinnvoll
Registriert: Di Okt 03, 2006 14:07 Beiträge: 1277 Wohnort: Wien
Tja, ich hab auch das mit den 1-2 Zeilen angeklickt. Scheint auf ein eindeutiges Ergebnis rauszulaufen.
Ich habe vor ein paar Jahren für mich selber ein paar Richtlinien aufgestellt, die da lauten:
1. Jedwede Doku hat in Englisch zu erfolgen (nicht weil ich das Zeug verkaufe, sondern um mich ein wenig zu üben)
2. Sprechende Bezeichnungen verwenden; in Pascal hat man es damit leicht
3. Variablen möglichst so strukturieren, dass im Code leicht zu erkennen ist, was da vorgeht (Ausnahmen sind nur zugelassen, wenn dadurch der Code leidet, es könnte ja z.B. langsamer werden). Sollte das nicht machbar sein, muss Textkommentar her.
4. Und das Wichtigste von allen: Methoden, Prozeduren und Funktionen (also Prozesse) sollen möglichst kurz sein. Man sollte sie auf einen Blick erfassen können. Sie sollten daher nicht mehr Zeilen haben, als auf den Bildschirm draufgehen (hört sich ziemlich trivial an, was? Das ist meiner Meiung nach aber der Schlüssel zu wirklich großen Applikationen). Es war nur in ganz seltenen Fällen nötig, diese Regel zu durchbrechen.
5. Wenn man ein Stück Code geschrieben hat, hat man zu überlegen, ob es eine einfachere Variante dazu gibt. Wenn die Antwort "Ja" lautet, hat man die einfachere Variante zu nehmen. Kompliziert wirds ohnehin von allein.
Traude
NACHTRAG: wie immer hab ich noch was vergessen: Man sollte sich immer ganz genau überlegen, wer (ich meine: welches Objekt oder welche Prozedur) für ein bestimmtes Codestück logischerweise zuständig ist. Hilft auch viel, wenn man später was ändern muss, wenn man auf die Überlegung "Wo müsste sich das eigentlich befinden?" auf Anhieb die richtige Antwort findet.
Nachdem die Umfrage über die Doku des codes(pfui Anglizismus) nein Quelltextes geht, habe ich auch die 1-2 Zeilen gewählt. Bei z.B.: Schnittstellenbeschreibungen ists deutlich mehr, da diese ja von anderen benutzt werden können sollen (haben sein). Dazu kommt dann eine Hilfe für das fertige Programm (für den Nutzer). Das hilft dabei, grobe Schnitzer in der Bedienung zu entfernen (nicht mehr als drei Klicks für eine Funktion usw.).
_________________ Manchmal sehen Dinge, die wie Dinge aussehen wollen, mehr wie Dinge aus, als Dinge.
<Esmerelda Wetterwax>
Es kann vorkommen, dass die Nachkommen trotz Abkommen mit ihrem Einkommen nicht auskommen und umkommen.
Mitglieder in diesem Forum: 0 Mitglieder und 5 Gäste
Du darfst keine neuen Themen in diesem Forum erstellen. Du darfst keine Antworten zu Themen in diesem Forum erstellen. Du darfst deine Beiträge in diesem Forum nicht ändern. Du darfst deine Beiträge in diesem Forum nicht löschen. Du darfst keine Dateianhänge in diesem Forum erstellen.