Files |  Tutorials |  Articles |  Links |  Home |  Team |  Forum |  Wiki |  Impressum

Aktuelle Zeit: Do Mär 28, 2024 21:21

Foren-Übersicht » DGL » Umfragen
Unbeantwortete Themen | Aktive Themen



Ein neues Thema erstellen Auf das Thema antworten  [ 24 Beiträge ]  Gehe zu Seite 1, 2  Nächste

Wie dokumentiert ihr euren Code?
Mit einem externen Schreibprogramm. (Word) 2%  2%  [ 1 ]
Ich lass es aus dem Code generieren. (Doxygen, Javadoc) 14%  14%  [ 8 ]
Ich hab im Code große Dokupassagen. 7%  7%  [ 4 ]
Bei den interessanten Stellen stehen 1-2 Zeilen im Code. 70%  70%  [ 39 ]
Mir war gar nicht klar das Doku wichtig sein könnte. 4%  4%  [ 2 ]
Doku is was für Anfänger. Ich hab das alles im Kopf. 4%  4%  [ 2 ]
Abstimmungen insgesamt : 56
Autor Nachricht
 Betreff des Beitrags: Wie dokumentiert ihr euren Code
BeitragVerfasst: Di Mär 13, 2007 19:55 
Offline
Guitar Hero
Benutzeravatar

Registriert: Do Sep 25, 2003 15:56
Beiträge: 7804
Wohnort: Sachsen - ERZ / C
Programmiersprache: Java (, Pascal)
Start. 13.03.07

_________________
Blog: kevin-fleischer.de und fbaingermany.com


Nach oben
 Profil  
Mit Zitat antworten  
 Betreff des Beitrags:
BeitragVerfasst: Di Mär 13, 2007 19:58 
Offline
Guitar Hero
Benutzeravatar

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


Nach oben
 Profil  
Mit Zitat antworten  
 Betreff des Beitrags:
BeitragVerfasst: Di Mär 13, 2007 20:00 
Offline
Ernährungsberater
Benutzeravatar

Registriert: Sa Jan 01, 2005 17:11
Beiträge: 2067
Programmiersprache: C++
Für Delphi gibt es auch PasDoc ;)

_________________
Steppity,steppity,step,step,step! :twisted:
❆ ❄ ❄ ❄ ❅ ❄ ❆ ❄ ❅ ❄ ❅ ❄ ❅ ❄ ❄
❄ ❄ ❄ ❅ ❄ ❄ ❄ ❅ ❄ ❄ ❆ ❄ ❄


Nach oben
 Profil  
Mit Zitat antworten  
 Betreff des Beitrags:
BeitragVerfasst: Di Mär 13, 2007 20:25 
Offline
DGL Member
Benutzeravatar

Registriert: Sa Dez 28, 2002 11:13
Beiträge: 2244
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.


Nach oben
 Profil  
Mit Zitat antworten  
 Betreff des Beitrags:
BeitragVerfasst: Di Mär 13, 2007 23:50 
Offline
DGL Member

Registriert: Di Jun 06, 2006 09:59
Beiträge: 474
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 ;)


Nach oben
 Profil  
Mit Zitat antworten  
 Betreff des Beitrags:
BeitragVerfasst: Mi Mär 14, 2007 14:07 
Offline
DGL Member
Benutzeravatar

Registriert: Di Sep 03, 2002 15:08
Beiträge: 662
Wohnort: Hamburg
Programmiersprache: Java, C# (,PhP)
Bei Methoden die publik sind nutz ich JavaDoc, ansonsten auch die guten alten Einzeilerkommentare.

_________________
(\__/)
(='.'=)
(")_(")


Nach oben
 Profil  
Mit Zitat antworten  
 Betreff des Beitrags:
BeitragVerfasst: Mi Mär 14, 2007 14:20 
Offline
DGL Member
Benutzeravatar

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.

_________________
www.SaschaWillems.de | GitHub | Twitter | GPU Datenbanken (Vulkan, GL, GLES)


Nach oben
 Profil  
Mit Zitat antworten  
 Betreff des Beitrags:
BeitragVerfasst: Mi Mär 14, 2007 17:06 
Offline
DGL Member
Benutzeravatar

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


Nach oben
 Profil  
Mit Zitat antworten  
 Betreff des Beitrags:
BeitragVerfasst: Mi Mär 14, 2007 17:47 
Offline
Fels i.d. Brandung
Benutzeravatar

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..."


Nach oben
 Profil  
Mit Zitat antworten  
 Betreff des Beitrags:
BeitragVerfasst: Mi Mär 14, 2007 20:51 
Offline
Guitar Hero
Benutzeravatar

Registriert: Do Sep 25, 2003 15:56
Beiträge: 7804
Wohnort: Sachsen - ERZ / C
Programmiersprache: Java (, Pascal)
Zitat:
zwei Flugzeugen irgendwo in der Weltgeschichte unterwegs sind und sich in der Mitte treffen.

Ich will niemals im selben Flugzeug sitzen wie Phobeus! :mrgreen:

_________________
Blog: kevin-fleischer.de und fbaingermany.com


Nach oben
 Profil  
Mit Zitat antworten  
 Betreff des Beitrags:
BeitragVerfasst: Mi Mär 14, 2007 22:07 
Offline
DGL Member

Registriert: Sa Okt 22, 2005 20:24
Beiträge: 291
Wohnort: Frauenfeld/CH
also ich hab auch ein paar zeilen im quelltext drin, aber nicht wirklich viel, bei den komplizierteren sachen steht dann scho mal jede 2te zeile was.

_________________
bester uo-shard: www.uosigena.de


Nach oben
 Profil  
Mit Zitat antworten  
 Betreff des Beitrags:
BeitragVerfasst: Do Mär 15, 2007 08:02 
Offline
DGL Member

Registriert: Do Mai 30, 2002 18:48
Beiträge: 1617
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 ;-)


Nach oben
 Profil  
Mit Zitat antworten  
 Betreff des Beitrags:
BeitragVerfasst: Do Mär 15, 2007 10:23 
Offline
DGL Member
Benutzeravatar

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.


Nach oben
 Profil  
Mit Zitat antworten  
 Betreff des Beitrags:
BeitragVerfasst: Do Mär 15, 2007 11:15 
Offline
DGL Member

Registriert: Mo Dez 20, 2004 08:58
Beiträge: 442
Wohnort: Mittweida (Sachsen)
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.


Nach oben
 Profil  
Mit Zitat antworten  
 Betreff des Beitrags:
BeitragVerfasst: Do Mär 15, 2007 12:05 
Offline
DGL Member
Benutzeravatar

Registriert: Di Okt 03, 2006 14:07
Beiträge: 1277
Wohnort: Wien
I0n0s schrieb:
Zitat:
Für Delphi gibt es auch PasDoc :wink:


Oje, das kommt auch noch auf mich zu. :( Hab ich mir bisher auch nur aus der Entfernung angesehen.


Nach oben
 Profil  
Mit Zitat antworten  
Beiträge der letzten Zeit anzeigen:  Sortiere nach  
Ein neues Thema erstellen Auf das Thema antworten  [ 24 Beiträge ]  Gehe zu Seite 1, 2  Nächste
Foren-Übersicht » DGL » Umfragen


Wer ist online?

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.

Suche nach:
Gehe zu:  
cron
  Powered by phpBB® Forum Software © phpBB Group
Deutsche Übersetzung durch phpBB.de
[ Time : 0.049s | 18 Queries | GZIP : On ]