Kommentare - was kommt alles rein?
-
Servus,
was sollte in den
- Headerkommentaren / Klassenkommentaren
- Funktionskommentaren
alles drinstehen? Gibt es da Richtlinien?danke im voraus
-
richtlinien gibts massenweise für sowas aber im prinzip kannste alles reinhauen was du sinnvoll findest
-
Dass ne Erläuterung der Funktion/Klasse/Wasauchimmer und ne Beschreibung von Rückgabewert und Parametern rein sollte, ist ja klar, aber was min. genauso wichtig ist, sind Seiteneffekte und Annahmen die innerhalb auftreten/gemacht werden.
Ansonsten ist ne Info über die verwendeten Algorithmen und Laufzeit je nachdem auch interressant zu wissen.
-
einige behaupten guten code müsse man nicht kommentieren, weil er eh' selbsterklärend sei. das ist natürlich unsinn bzw. eine idealvorstellung die aber nicht viel mit der wirklichkeit zu tun hat.
-
Schorsche schrieb:
Servus,
was sollte in den
- Headerkommentaren / Klassenkommentaren
- Funktionskommentaren
alles drinstehen? Gibt es da Richtlinien?kommt auf die sprache an. deswegen gibt's auch immer wieder die mißverständnisse. brainfuck muß man sehr stark kommentieren. c muß man stark kommentieren. für java reicht ein wenig für javadoc. c++ besser nur in ausnahmen kommentieren.
-
Programmiersprache Java.
Ich hab mir mal die Java Code Conventions angeschaut, aber ich weiß noch nicht genau was in die Klassenbeschreibung rein soll.
(Für eine Spielkarte)/** * ?????? * @version 1.00 from 10.10.05 * @author Schorsch@localhost */ class GameCard ...Was könnte man da so alles schreiben?
-
net schrieb:
einige behaupten guten code müsse man nicht kommentieren, weil er eh' selbsterklärend sei. das ist natürlich unsinn bzw. eine idealvorstellung die aber nicht viel mit der wirklichkeit zu tun hat.
Wobei damit i.d.R. inline Kommentare gemeint sind, also Kommentare die in der Implementation stehen, nicht etwa die an Köpfen von Methoden bzw. im Header. Diese Code-Kommentare enthalten eh in 90% der Fälle Trivialitäten und werden viel zu oft nicht (oder nicht richtig) gepflegt, wenn der Code sich weiterentwickelt und führen daher nur zu weiterer Verwirrung. (Letztlich ist es damit wohl wie mit der ungarischen Notation, die aufgrund gleicher Bedingungen auch oft eher schaden kann als nützt.)
-
man muss ja die pre/post conditions dokumentieren!
-
volkard schrieb:
Schorsche schrieb:
Servus,
was sollte in den
- Headerkommentaren / Klassenkommentaren
- Funktionskommentaren
alles drinstehen? Gibt es da Richtlinien?kommt auf die sprache an. deswegen gibt's auch immer wieder die mißverständnisse. brainfuck muß man sehr stark kommentieren. c muß man stark kommentieren. für java reicht ein wenig für javadoc. c++ besser nur in ausnahmen kommentieren.
schonmal open source projekte angeguckt? da ist auch fast nie was dokumentiert. und dementsprechend schlecht findet man sich zurecht. ok man muss dazu sagen, die meisten sind ja in c/c++ geschrieben anstatt in c++.
-
Schorsche schrieb:
Programmiersprache Java.
Ich hab mir mal die Java Code Conventions angeschaut, aber ich weiß noch nicht genau was in die Klassenbeschreibung rein soll.
(Für eine Spielkarte)/** * ?????? * @version 1.00 from 10.10.05 * @author Schorsch@localhost */ class GameCard ...Was könnte man da so alles schreiben?
Ich finde die Java-Docs sind vorallem wichtig für Teams, damit man nur einen Blick in die Docu werfen muss um zu sehen, was die Funktionen machen und nicht es aus dem Code herausfinden.
-
Kommentare, aus denen ein beliebiges Programm (zB Doxygen) eine schöne Doku formen kann sind eigentlich nicht schlecht, weil man so leicht ein Code Verständnis gewinnt. Der Nachteil ist, dass man dazu neigt absolut unnötige Kommentare einzufügen.
Ansonsten sollte man stellen kommentieren, die auf dem ersten Blick nicht offensichtlich sind. Wobei man sich fragen sollte, ob man gerade einen solchen Kommentar hinzufügt, weil der Code schlecht geschrieben ist.