Wie kommentiert ihr?

[byto]

Nicht mehr dokumentieren als zum groben Verständnis nötig. Schließlich muss man die Doku beim Code-Refactoring immer mitpflegen. Je kürzer die Dokumentation, umso leichter fällt das. Je leichter es fällt, umso häufiger wirds gemacht.

Und nichts ist schlimmer, als eine veraltete (falsche) Dokumentation. Die ist dann nämlich schlechter als gar keine Doku weil irreführend!

[loks]

Der Fehler des OP ist es, Kommentierung und Dokumentation durcheinanderzuwerfen.

Dokumentation sollte Lückenlos sein, also auch so eine Trivialfunktion wie GetSize() muss Dokumentiert sein, auch wenn es offensichtlich ist. Grund: In der Dokumentation erscheint _kein_ Sourcecode. Das Argument: "der Sourcecode erklärts" greift hier also nicht.

Nebenbei: Der Dokumentationseintrag sollte beschreiben was die Funktion machen _soll_. Wenn die GetSize() Funktion dokumentiert ist als: Ermittel die Größe, in Wirklihckeit aber etwas ganz anderes liefert ist es leichter diesen Bug zu finden, besonders wenn der Tester nicht der Programmierer ist. Die Dokumentation kann man hier betrachten als: "Das wollte ich machen" und der Sourcecode ist dann "Das habe ich gemacht". Wenn die beiden nicht übereinstimmen liegt ein logischer Fehler im Code vor. Hier kommt man schnell in eine Zwickmühle: Man selber erkennt einen Logikfehler oft nciht eben weil man ihn für richtig hält. Ein anderer wiederum kann den Logikfehler nicht erkennen weil er nicht die Gedanken des Programmierers lesen und damit wissen kann was der eigendlich machen wollte.

Ganz anders sieht das mit Kommentierung aus. Hierauf bezieht sich auch das Zitat von Stroustrup.

Kommentierung im Stil:

int index;  // int varible mit Namen index

object.GetSize()  // Get the size form object

int main() // main-function
{
} // end main-function

etc sind einfach nur Schwachsinn und sogar Kontroproduktiv, weil man so unter 100 Zeilen sinnlosem Kommentar den einen wichtigen übersieht.

Sowas sieht man gerne in Tutorials (wo der Nutzen diskutabel ist) und Anfänger übernehmen diesen Stil dann gern.

Bei Kommentierung gilt wirklich: Nur kommentieren was nicht offensichtlich ist.

[Blue-Tiger]

byto schrieb:

tntnet schrieb:

Kommentare sollten nicht das enthalten, was das Programm tut. Das sieht man im Code.

Ich möchte mir aber nicht jedes Mal erst den Code angucken, um zu wissen, was eine Methode tut, wenn ich sie an einer beliebigen Stelle aufrufe.

Deshalb gibts sprechende Funktionsnamen

Schreibt ihr als noch den Aufwand in eure Dokumentation? Und wie stets mit dem Speicherverbrauch? Also ich meine hier keine konkreten Werte, sondern ein O(1), oder vllt. mit etwas mehr Information O(3n).

Wenns relevant ist ist schon, ja. Aber dass mein log2(x)-Hilfsfunktion in O(log n) statt in O(n) (mit n Anzahl Bits von x) arbeitet, interessiert z. B. niemand ( es sei denn ich schreibe eine Mathe-Library).
Aber dass mein findSimilarFiles(File f, Directory d) im "FindeDoppelteMP3s"-Programm in O(n*n) der Files im gegebenen Verzeichnis arbeitet, ist erwaehnenswert. Aber mehr als die Komplexitaetsklasse gibts da auch nicht.

[-fricky-]

loks schrieb:

Kommentierung im Stil:

...
} // end main-function

etc sind einfach nur Schwachsinn und sogar Kontroproduktiv

kommt drauf an, wie länglich deine 'main-function' ist.

[asc]

-fricky- schrieb:

kommt drauf an, wie länglich deine 'main-function' ist.

Zu große Funktionen deuten immer auf einen schlechten Stil hin. Funktionen sollten nur so groß sein das man sie noch sinnvoll überblicken und verstehen kann. Daher sehe ich diese Form der Kommentierung eh als Schwachsinn an.

cu André

[Shade Of Mine]

-fricky- schrieb:

loks schrieb:

Kommentierung im Stil:

...
} // end main-function

etc sind einfach nur Schwachsinn und sogar Kontroproduktiv

kommt drauf an, wie länglich deine 'main-function' ist.

nein. denn dafür hast du eine ide

mal abgesehen davon dass wenn eine funktion ueber mehr als eine seite geht, du andere probleme hast als kommentare...

[-fricky-]

asc schrieb:

Zu große Funktionen deuten immer auf einen schlechten Stil hin. Funktionen sollten nur so groß sein das man sie noch sinnvoll überblicken und verstehen kann. Daher sehe ich diese Form der Kommentierung eh als Schwachsinn an.

schon richtig, aber manchmal gibts switch/case-anweisungen die ganz schön lang sein können. da ist so'n kommentar */* end of switch(...) / gar nicht so verkehrt.

[Knuddlbaer]

mal abgesehen davon dass wenn eine funktion ueber mehr als eine seite geht, du andere probleme hast als kommentare...

z.B. die Realität wie Praxis oder Wirtschaftlichkeit - manchmal auch einfach switch Statements.

[byto]

-fricky- schrieb:

asc schrieb:

Zu große Funktionen deuten immer auf einen schlechten Stil hin. Funktionen sollten nur so groß sein das man sie noch sinnvoll überblicken und verstehen kann. Daher sehe ich diese Form der Kommentierung eh als Schwachsinn an.

schon richtig, aber manchmal gibts switch/case-anweisungen die ganz schön lang sein können. da ist so'n kommentar */* end of switch(...) / gar nicht so verkehrt.

Wo wir wieder beim schlechten Stil wären...

[-fricky-]

byto schrieb:

Wo wir wieder beim schlechten Stil wären...

was tust du denn z.b. gegen einem switch mit 30 cases?

[nosongnornoob]

by the hammer

[SideWinder]

Gibt verschiedene Möglichkeiten, zB:

methods[case].invoke();

MfG SideWinder

[-fricky-]

SideWinder schrieb:

Gibt verschiedene Möglichkeiten, zB:
methods[case].invoke();

das fängt nicht den default-fall ab. ausserdem erzeugen compiler für sitch/case-konstrukte sehr effizienten code, was bei einer tabelle mit function-pointern nicht immer gegeben ist. also ich finde es nie gut, performance gegen 'schönen code' zu tauschen.

[b]

mit C++-style kommentaren statt C-style kommentaren

[byto]

-fricky- schrieb:

byto schrieb:

Wo wir wieder beim schlechten Stil wären...

was tust du denn z.b. gegen einem switch mit 30 cases?

Polymorphie nutzen.

[Bashar]

byto schrieb:

Polymorphie nutzen.

Gratulation, du hast gerade eine Funktion zu 30 vom Designstandpunkt her völlig überflüssigen Klassen vereinfacht.

[SideWinder]

-fricky- schrieb:

SideWinder schrieb:

Gibt verschiedene Möglichkeiten, zB:
methods[case].invoke();

das fängt nicht den default-fall ab. ausserdem erzeugen compiler für sitch/case-konstrukte sehr effizienten code, was bei einer tabelle mit function-pointern nicht immer gegeben ist. also ich finde es nie gut, performance gegen 'schönen code' zu tauschen.

Ich würde immer Performance gegen "schönen Code" tauschen. Aber abgesehen davon, habe ich nicht behauptet, dass mein Code "schön" ist. Es war nur ein Beispiel. Das kommt dann immer auf das konkrete Beispiel an. Aber Dinge wie:

switch(errorcode)
{
    case 404: return NLS.get("DOC_NOT_FOUND"); break;
    ... // weitere 1000 fälle
}

rgen mich ganz furchtbar auf:

String str = NLS.get(errorMap.get(404));

MfG SideWinder

[SideWinder]

Wobei, wenn man tatsächlich mehr als 5 "Modi" hat die alle differenten Quellcode zur Ausführung bringen und die wirklich (meistens Designschwäche) durch das selbe switch abgedeckt werden sollen, würde ich schon auf dynamischen Methodenaufruf setzen (da brauch ich dann auch keinen default-Fall, denn default-mäßig ruft mein Benutzer nicht den Punkt File->Open auf ... im Notfall kommt eine NotFoundException und auf die kann ich dann reagieren).

MfG SideWinder

[-fricky-]

byto schrieb:

Polymorphie nutzen.

ich wusste doch, dass es noch sinnvolle anwendungen von OOP gibt.

SideWinder schrieb:

Wobei, wenn man tatsächlich mehr als 5 "Modi" hat die alle differenten Quellcode zur Ausführung bringen und die wirklich (meistens Designschwäche) durch das selbe switch abgedeckt werden sollen, würde ich schon auf dynamischen Methodenaufruf setzen.

die designschwächen machen aber oft andere (siehe dein beispiel mit dem http) und damit muss man leider leben.

SideWinder schrieb:

im Notfall kommt eine NotFoundException und auf die kann ich dann reagieren).

das halte ich wiederum für schlechten stil: exceptions einzusetzen, obwohl man mit einem einfachen 'if' testen kann, ob ein wert überhaupt gültig ist.

[tfa]

Bashar schrieb:

byto schrieb:

Polymorphie nutzen.

Gratulation, du hast gerade eine Funktion zu 30 vom Designstandpunkt her völlig überflüssigen Klassen vereinfacht.

Woher willst du das wissen? Vielleicht hat er auch unwartbaren Spaghetticode zu einem vernünftigen OO-Design gemacht.