Registriert: Sa Jan 01, 2005 17:11 Beiträge: 2067
Programmiersprache: C++
Traude hat geschrieben:
I0n0s schrieb:
Zitat:
Für Delphi gibt es auch PasDoc
Oje, das kommt auch noch auf mich zu. Hab ich mir bisher auch nur aus der Entfernung angesehen.
Och, so schwer ist es nicht, wobei ich bei der GUI eh sagen würde, dass es euch nicht bringt. Ihr habt ja eh ein Designdokument, und wenn man dann eine "richtige" Doku aus dem Quelltext erstellt ohne Hilfen wie Pasdoc könne man vielleicht nochmal Fehler im Design finden?
Registriert: Di Mai 18, 2004 16:45 Beiträge: 2622 Wohnort: Berlin
Programmiersprache: Go, C/C++
Ich bin in der Regel sehr Kommentarfaul aber ich arbeite dran. Ich hab die Tage für Pasdoc ein XML generator geschrieben, so kann man nun --format html,latex,Windows Hilfe und xml angeben. Ein php script erlaubt dann, das lesen der xml datein und kann somit in eigene Webseiten,CMS oder WIKI eingepflegt werden.
_________________ "Wer die Freiheit aufgibt um Sicherheit zu gewinnen, der wird am Ende beides verlieren" Benjamin Franklin
Registriert: Di Dez 27, 2005 12:44 Beiträge: 393 Wohnort: Berlin
Programmiersprache: Java, C++, Groovy
Hallo,
ich kommentier ziemlich knapp und nur wenn es wirklich notwendig ist.
Meine Devise ist lieber keine, als falsche oder verwirrende Kommentare zu setzen.
Man muss auch bedenken, dass man bei Änderungen am Quellcode nicht vergessen darf, seine Kommentierung aktuell zu halten (das vergessen einige), z.B. wenn sich Parameter in einer Funktion ändern oder ähnliches.
1. Jedwede Doku hat in Englisch zu erfolgen (nicht weil ich das Zeug verkaufe, sondern um mich ein wenig zu üben)
das ist mehr als sinnvoll, nachdem ich schwedischen und spanischen quellcode verarbeiten durfte merkt man, wie sinnvoll das ist, wenn eine gemeinsame verständigungsbasis besteht - auch bei Methoden- und Elementnamen.
Leider halt ich mich da selbst nicht immer dran, vorallem neig ich bei langen ausdrücken die abzukürzen, damit der quelltext sich nicht so schrecklich aufbläht - vorallem, wenn man längere ausdrücke mit nem dutzend variablen drin hat.
dann empfiehlt es sich aber eh den ausdruck aufzutrennen. wenn man es ordentlich macht wird der code dadurch nicht langsamer und debuggen lässt er sich auch einfacher.
aber wer kennt nicht den unterschied zwischen vorsatz und realität - vorallem wenn der chef meint, dass das quick&dirty-demo-programm ja seine aufgabe erfüllt und man jetzt was anderes tun könne
Vor allem, wenn man eine API schreibt, die auch andere benutzen sollen, sollte eine Kommentierung natürlich so gut wie möglich sein.
Bei eigenen Projekten mach ich das allerdings (wahrscheinlich aus Faulheit ) eher selten so umfangreich.
Du weisst das man für die Parameter, sofern sie aus dem JDK oder jedweder anderen Doku die Verlinkung nicht selbst vornehmen muss? Man muss sie lediglich beim Build referenzieren und JavaDoc macht den Rest.
Und die Ein/Ausgabe Parameter lassen sich sehr gut via @param name beschreibung setzen
Registriert: Do Sep 02, 2004 19:42 Beiträge: 4158
Programmiersprache: FreePascal, C++
Also, normalerweise schreibe ich nur an wirklich wichtigen Stellen Kommentare. Meine Variablen-, Prozeduren-, Funktionen- und Methodennamen wähle ich immer so, dass ich sie später wiedererkenne (Was heißt, Zählvariablen sind immer I, I1, I2... Aber sonst ist alles gründlich benannt). Dafür habe ich mir das Was-Würde-Jemand-Bei-Diesem-Namen-Denken-Wenn-Er-Das-Projekt-Nur-Im-Groben-Umriss-Kennt-Denken angewöhnt. Das kann durchaus hilfreich sein, seit dem verstehe ich meinen Code, selbst wenn ich ihn Wochenlang liegengelassen habe und mich mit PHP oder sonstwas beschäftigt habe.
Vor kurzem habe ich einen bereich im Code genauer dokumentiert um an den Fehler zu kommen, weil ich beim Kommentieren nochmals überdenke, was die einzelnen Calls eigentlich machen. Das hat mir letzlich auch geholfen (habe anstatt auf den Parameter auf das Result zugegriffen, wobei beide vom gleichen Typ waren...)
Gruß Lord Horazont
_________________ If you find any deadlinks, please send me a notification – Wenn du tote Links findest, sende mir eine Benachrichtigung. current projects: ManiacLab; aioxmpp zombofant network • my photostream „Writing code is like writing poetry“ - source unknown
„Give a man a fish, and you feed him for a day. Teach a man to fish and you feed him for a lifetime. “ ~ A Chinese Proverb
Mitglieder in diesem Forum: 0 Mitglieder und 3 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.