Wie richtig kommentieren?

[icarus2]

Huhu

Ich habe mich schon öfters gefragt wie ich richtig kommentiere. Schreibe ich kommentare mit @param und @return da vo ich die Methode aufrufe, nur da wo sie geschrieben ist, oder an beiden Orten.

Ich möchte mir gerne mal ein par Klassen anschauen, z.B. die Klassen aus dem Paket java.lang


Aber wie komme ich an diese Klassen hin?

 

[Wildcard]

@param @returns usw. sind für Java-Doc. Mit Code Kommentaren hat das wenig zu tun.
Davon abgesehen ist der Quellcode im JDK enthalten, aber wenn es dir um die Java Doc geht reicht auch das:
Java Platform SE 6

 

[icarus2]

Heisst das hier wäre schlecht kommentiert?

[Java]

/*
* Checks if the current position of the queen is threatened or not
*
* @param int k, to state at which horizontal position the vertical position
* must be checked.
* @return: If the position is free it returns true, if the position is threatened it returns false
*/
private boolean checkPosition(int k){

.....
.....

return posFree;
}

[/Java]

 

[Wildcard]

Sieht aus wie Java-Doc, ist aber keins. Gibt es einen bestimmten Grund warum du das nicht als JavaDoc Kommentar schreibst?

 

[Schandro]

... es ist kein Javadoc, weil am Anfang des Kommentarblockes das hier stehen muss:

/**

Bei dir fehlt ein Stern


€dit: ;( irgendwie ist mein 1.000er Beitrag ziemlich unspektakulär ^^

 

[icarus2]

Ich will nur das ganze kommentieren. Habe bei den Code-Schnippseln gesehen, dass z.B. Marco das ganze so kommentiert hat.

Kann mir jmd bitte sagen wie ich den das sonst machen könnte, vielleicht mal mit eigenem geproggten Code-Schnippsel?


Edit:

Was ist genau eine Javadoc und wie kann ich die in Eclipse erstellen?

Edit 2:
Ich wusste nicht, dass man dafür /** schreibt. Wird aber nachgeholt ;-)

 

[Schandro]

geh mal in Eclipse eine Zeile vor eine Methode/Klassse/Variable.
Dann drückst du
/**
und dann Enter

dann erstellt dir Eclipse das Grundgerüst für Javadoc für die jeweilige Methode/Klassse/Variable

 

[icarus2]

Aso, danke

Das funktioniert eben auch mit /* + Enter... werde es aber jetzt so machen wie du gesagt hast.


[Java]
/**
* Checks if the current position of the queen is threatened or not
*
* @param int k, to state at which horizontal position the vertical position
* must be checked.
* @return: If the position is free it returns true, if the position is threatened it returns false
*/
private boolean checkPosition(int k){
boolean posFree = true;

//Checks if the current checked position is threated by a previous queen (one which is placed
//further left than the current).
for(int i=0 ; i<k ; i++){

trials++; //After every checked position, trials is incremented by 1.
amoutOfTrials.setText("Amount of Trials: "+trials); //Label which shows the amount of trials is updated

if(Math.abs( f- f[k] ) == k - i | f == f[k]){
posFree = false;
break;
}
}


return posFree;
}
[/Java]

Ist das so gut kommentiert?

 

[Schandro]

lass lieber Doppelpunkt nach return weg.

* @param int k, to state at which horizontal position the vertical position
* must be checked.

So wärs richtig:

* @param k to state at which horizontal position the vertical position
* must be checked.

Um zu gucken ob du die Javadoc richtig formatiert hast, kannst du einfach in Eclipse über den Methodennamen mit dem Mauszeiger gehen. Dann wird dir deine Javadoc formatiert angezeigt.

 

[icarus2]

Guter Tipp mit dem Methodennamen, hab ich bisher noch nicht gesehen


Vielen Dank Schandro und Wildcard

 

[Marco13]

Ich will nur das ganze kommentieren. Habe bei den Code-Schnippseln gesehen, dass z.B. Marco das ganze so kommentiert hat.

Was ... meinst du?

 

[icarus2]

Ich hatte nur mal etwas angeschaut wie die Leute ihre Codes kommentieren und versuchte es so zu machen wie du, da ich denke du weisst wie man das richtig macht ;-)

Hab ein bisschen bei dem Code hier geschaut: Dein Code

 

[Marco13]

Naja. Eigentlich finde ich, dass man ALLE Methoden kommentieren sollte - und zwar sinnvoll. Also Javadoc-Kompatibel, und so, dass man nachvollziehen kann, WAS dort WARUM und WIE gemacht wird. Das ist da jetzt nicht 100% der Fall aber ... naja...

 

[icarus2]

Mag sein. Aber dafür hab ich das bei dir gesehen mit @param und so ;-)

 

[maki]

Ich finde private Methoden/Attribute sollten nie kommentiert werden, dass sind interna, wenn man sich dafür interessiert, sollte man sich den Quellcode ansehen.

 

[Marco13]

Natürlich sollten (vielleicht GERADE) die kommentiert werden! Die Schnittstelle sind ja nur die (im Idealfall: wenigen) public und (noch wenigeren) protected Methoden. Wenn man nachvollziehen will, was der Code macht, braucht man ggf. schon auch Kommentare für die privaten Sachen.

 

[tfa]

Meinte maki vielleicht, dass man private Member nicht dokumentieren (also Java Doc-Kommentare) braucht?

 

[maki]

JavaDoc ist imho nicht angebracht bei privaten Methoden, genausowenig wie private Member.

Internas können sich schnell ändern, da ist mir sauberer Code lieber als veraltete Kommentare, vor allem lügt Code im Gegensatz zu Kommentaren nie.
Wenn die Methoden richtig benannt und strukturiert sind, erübrigen sich Kommentare meist, da sie dann nicht wirklich zusätzlichen Wert haben.
Wenn ich wirklich nachvollziehen will was der Code macht, dann lese ich den Code, sollte aber im Idealfall überflüssig sein, denn der Name der Methode sollte so aussagekräftig sein dass ich keine Überraschungen erlebe wenn ich den Code dazu lese.

icarus Beispiel finde ich da sehr passend, da wird fachlicher Code und GUI Code gemischt (SOC wird verletzt), das würde ich nicht erwarten wenn überprüft werden soll ob die Königin angegriffen werden könnte.
Wenn man nun noch den Paramter k (!!!) vernünftig benennt muss man ihn auch nicht mehr Dokumentieren, er würde sich selbst dokumentieren, dasselbe gilt für den namen der Position, etwas mehr Info als "checkPosition" und schon bräuchte man den return Wert nicht mehr erklären.
Wenn man sich dabei erwischt so etwas zu kommentieren sollte man den Code überdenken.

Gemessen daran wie oft Code gelesen wird wird imho viel zuwenig an dessen aussagekraft gedacht, "Hauptsache es geht" ist nicht wirklich gut genug.

Nachtrag: Diese Zeile ist auch so ein Fall für ein Mikro-Refactoring anstatt eines Kommentares:

if(Math.abs( f[i]- f[k] ) == k - i | f[i] == f[k]){

 

[musiKk]

Ich denke, man kann es auch vertreten, private Methoden zu dokumentieren. Vor allem bei größeren Projekten, an denen potentiell mal viele Leute arbeiten sollen (z. B. oder gerade bei OSS), kann man so neben einer Dokumentation für Anwender auch eine Developer-Doku erstellen. Dass sich private Methoden oft ändern, mag ja stimmen, aber ich halte es für mich immer so, dass ich sobald ich das erste Mal noch einmal kurz nachdenken muss, was eine private Methode macht, dieser einen JavaDoc-Kommentar verpasse (sofern ich der Meinung bin, dass das Design trotzdem Ok ist).
Letzten endes ist man beim Bearbeiten von Code immer dafür verantwortlich, alle betroffenen Kommentare zu prüfen, public oder nicht.

 

[maki]

Speziell in größeren Projekten zahlt es sich aus sauberen Code zu schreiben.

Dass die Doku immer vernachlässigt wird ist kein Geheimnis, sobald eine Methode nicht klar ist und man ein Kommentar schreiben will, zahlt sich refactoring aus, denn damit wird nicht nur unverständlicher Code erklärt, sondern die Struktur vom Code verbessert, was wiederrum das Kommentar überflüssig macht und den Code verbessert.

Nicht umsonst werden Kommentare als "Code smell" bezeichnet

 

[tuxedo]

Private Methoden nicht kommentieren? Wo gibts denn sowas?

Wir haben hier ein recht großes Projekt, bestehend aus rund 6000 Java-Source-Files.

Nach 2 Jahren Entwicklung mit 30 Mann ist es durchaus hilfreich wenn auch private Methoden dokumentiert/kommentiert sind. Saß schon oft vor einer Methode, die nicht dokumentiert war, deren Source recht "easy" zu lesen war, aber kaum einer wusste wozu die Methode da war und wie sie ins "Gesamtbild" passt. Und im schlimmsten Fall wusste entweder keiner mehr wer diese Methode gemacht hat. Und in anderen Fällen gab es denjenigen gar nicht mehr in der Firma der das verbrochen hat. Und somit war/ist auch das Wissen über das "wieso und wie" erstmal weg und man muss sich das erst wieder "erarbeiten".

Aber auch bei kleineren Projekten (z.B. bei meinen eigenen, privaten), dokumentiere ich alles. Denn auch hier hab ich mir schon zu oft den Kopf drüber zerbrochen wieso ich Methoden so implementiert hab wie ich sie implementiert hab...

Das "was macht die Methode" im Klassischen JavaDoc Stil ist denke ich nicht ganz so wichtig bei privaten Methoden. Viel wichtiger finde ich das "wieso und warum" und vor allem "wie", und bei Projekten mit mehreren beteiligten auch noch das "wer".

- Alex

 

[maki]

Private Methoden nicht kommentieren? Wo gibts denn sowas?

zB. in sauber geschriebenen open source Projekten, sieh dir doch mal zB. die Quellen von JUnit an.

Saß schon oft vor einer Methode, die nicht dokumentiert war, deren Source recht "easy" zu lesen war, aber kaum einer wusste wozu die Methode da war und wie sie ins "Gesamtbild" passt.

Hört sich an als ob die Merthode doch nicht so easy zu lesen war... Stichwort "Intention releaving names/Interfaces".

Viel wichtiger finde ich das "wieso und warum" und vor allem "wie", und bei Projekten mit mehreren beteiligten auch noch das "wer".

Das SCM hat die Aufgabe das "wer" festzuhalten, so etwas gehört nicht in den Quellcode, ausser man programmiert noch im Stil von PL/1. (Bei Public Methoden kann man java das @Author JavaDoc Tag nutzen)
Das "wie" wird am besten vom Code selber beschrieben, denn dass gehört zu den interna die man eigentlich abstrahieren möchte.
Das "was" sollte am besten von der Methode (Name) und deren Parametern beschrieben werden.

Wie gesagt, zuviele Kommentare werden als Code smell bezeichnet, weil damit meist schlecht geschriebener Code erklärt werden soll, und dass ist genaugenommen Zeitverschwendung
"If it was hard to write, so it should be hard to read" ist die falsche Einstellung.

Das man für die Public Schnittstellen ein JavaDoc kommentar macht ist natürlich ok, solange sie auch wirklich einen Mehrwert haben.

Nachtrag: Es ist kein Zufall dass die Standardeinstellung des JavaDoc Tools keine privaten Methoden mitaufführt.

 

[tuxedo]

>> Das SCM hat die Aufgabe das "wer" festzuhalten, so etwas gehört nicht in den Quellcode

Prima. Du hast also ein Projekt vor dir mit rund 6000 Klassen und versuchst herauszufinden wieso etwas gemacht wurde wie es gemacht wurde. Wenn nun mehrere Entwickler an einer Klasse gearbeitet haben - und ich bin mir sicher dass das bei großen Projekten nicht selten ist - dann hab ich mit der Tatsache, dass ja im SCM das ganze "wer" festgehalten wurde ein kleines Problem... Wenn die Methode in der Klasse, für die ich mich interessiere nun 2 Jahre alt ist such ich mir nen Wolf. Da wäre ein kleiner Hinweis wer's verbrochen hat schon hilfreich. Damit nicht bei jeder Methode der Autor mit dabei steht kann man ja im Kopf der Methode die Autoren aufführen. Werden ja schon keine 200 sein, so dass man die 5, die es letztendlich wirklich waren schnell abgeklappert und seine gewünschte Info eingeholt hat.

>> Das "wie" wird am besten vom Code selber beschrieben, denn dass gehört zu den interna die man eigentlich abstrahieren möchte.

Nicht jede Methode hat nur eine Hand voll zeilen und sind schnell zu überschauen. Klar, es ist ein gewisser mehr Aufwand Code-Kommentare up2date zu halten wenn sich etwas ändert. Aber ich bin davon überzeugt dass es das Wert ist. Wie die "Realität" (JUnit und Co.) aussieht ist mir persönlich dabei absolut Schnuppe. Wenn ich nach 2 Jahren ein recht komplexes Codekonstrukt wieder vor mir hab, dann will ich das nicht ausschließlich anhand des Codes verstehen. An so manchen Stellen bau ich mittels Code Comments Hintergrundinformationen ein dir mir selbst helfen auch nach Jahren noch zu verstehen wieso ich das gerade so und nicht anders gemacht habe. Denn DAS geht nicht aus dem Code selbst hervor.

Und wer schonmal durch den JRE Source geschaut hat, wird auch dort Kommentare zwischen den Zeilen vorfinden. Ich sag ja nicht dass jede Zeile kommentiert werden soll. Aber kategorisch Kommentare iund Infos (ja, ist noch die Rede von Kommentaren, und nicht nur JavaDoc) in nicht public Methoden zu "verteufeln", und solchen Code dann als "schlecht" hinzustellen finde ich etwas engstirnig und falsch.

>> "If it was hard to write, so it should be hard to read" ist die falsche Einstellung.

Jepp. Definitiv. Aber das heisst nicht, dass jeder Code und Kontext einfach zu formulieren ist, und demnach Code, der nicht in 5min verstanden werden kann schlecht ist. Zusammenhänge lassen sich IMHO schneller verstehen wenn die eine oder andere Kommentarzeile vorhanden ist, die das aufklärt, was "zwischen den Codezeilen" gemeint ist.

In diesem Sinne: Jeder sollte kommentieren wie er's für richtig hält. Verallgemeinern kann man die Sache sicherlich nicht bis ins Detail.

- Alex

 

[musiKk]

Viel wichtiger finde ich das "wieso und warum" und vor allem "wie", und bei Projekten mit mehreren beteiligten auch noch das "wer".

Idealerweise würde man das "was" in der Dokumentation des Interfaces schreiben und das "wie" zu den implementierenden Klassen, sodass man sich leicht für die geeignete Implementierung im jeweiligen Anwendungsfall entscheiden kann.

 

[maki]

Prima. Du hast also ein Projekt vor dir mit rund 6000 Klassen und versuchst herauszufinden wieso etwas gemacht wurde wie es gemacht wurde. Wenn nun mehrere Entwickler an einer Klasse gearbeitet haben - und ich bin mir sicher dass das bei großen Projekten nicht selten ist - dann hab ich mit der Tatsache, dass ja im SCM das ganze "wer" festgehalten wurde ein kleines Problem... Wenn die Methode in der Klasse, für die ich mich interessiere nun 2 Jahre alt ist such ich mir nen Wolf. Da wäre ein kleiner Hinweis wer's verbrochen hat schon hilfreich. Damit nicht bei jeder Methode der Autor mit dabei steht kann man ja im Kopf der Methode die Autoren aufführen. Werden ja schon keine 200 sein, so dass man die 5, die es letztendlich wirklich waren schnell abgeklappert und seine gewünschte Info eingeholt hat.

Das Subversisve Plugin für Eclipse macht das sehr gut, Revisionen mit Änderungen werden fett angezeigt, ansonsten geht das auch mit den Kommandozeilentools ziemlich einfach.
Nachteilig an der "alten" Art festzuhalten wer wann was gemacht hat ist eben dass der Quellcode so zugeüllt wird mit Meta-Infos die eigentlich schon im SCM stehen.

Nicht jede Methode hat nur eine Hand voll zeilen und sind schnell zu überschauen.

Aber jede Methode kann dazu refactored werden, und das ist genau der Punkt, wann ist Code "fertig"?
Wenn er funktioniert? Code zu schreiben der vom Compiler verstanden wird ist einfach, Code zu schreiben der vom Menschen verstanden wird ist die Kunst.
Wie gesagt, gemessen daran wie oft Code gelesen wird wird imho viel zuwenig auf die Struktur geachtet.

Klar, es ist ein gewisser mehr Aufwand Code-Kommentare up2date zu halten wenn sich etwas ändert. Aber ich bin davon überzeugt dass es das Wert ist.

Dieser Aufwand wäre beim Refactoring besser aufgehoben.

Wie die "Realität" (JUnit und Co.) aussieht ist mir persönlich dabei absolut Schnuppe.

Du hattest gefragt

Wenn ich nach 2 Jahren ein recht komplexes Codekonstrukt wieder vor mir hab, dann will ich das nicht ausschließlich anhand des Codes verstehen. An so manchen Stellen bau ich mittels Code Comments Hintergrundinformationen ein dir mir selbst helfen auch nach Jahren noch zu verstehen wieso ich das gerade so und nicht anders gemacht habe. Denn DAS geht nicht aus dem Code selbst hervor.

Wenn der Code sauber genug wäre, wären Kommentare so gut wie überflüssig, und genau das ist der Punkt.
Klarheit im Code durch Kommentare zu erreichen hat viele Nachteile, vor allem aber wird der Code selber dadurch nicht klarer.

Und wer schonmal durch den JRE Source geschaut hat, wird auch dort Kommentare zwischen den Zeilen vorfinden. Ich sag ja nicht dass jede Zeile kommentiert werden soll. Aber kategorisch Kommentare iund Infos (ja, ist noch die Rede von Kommentaren, und nicht nur JavaDoc) in nicht public Methoden zu "verteufeln", und solchen Code dann als "schlecht" hinzustellen finde ich etwas engstirnig und falsch.

Die JRE/JDK Sourcen sind auch kein gutes Beispiel, zumindest meist.
"Verteufeln" will ich es nicht, aber klarstellen das es keine "gute Sache" ist.

Klar habe ich das auch gemacht, klar habe ich auch mal private Member dokumentiert (unsinnig, vor allem der Inhalt meiner Kommentare).
Früher war es gang und gäbe so viele Kommentare wie nur möglich einzufügen, mittlerweile hat sich (vor allem in OO Sprachen) diese Einstellung geändert.

"Refactoring: Improving the Design of Existing Code" von Fowler und "Clean Code" von Robert Martin fand ich ganz gut wenn es darum geht Struktur in den Code zu bringen.

 

[Beni]

Ich bin auf der Seite der "kommentiere alles"-Fraktion. Das Ideal, dass Quellcode sich selbst kommentiert, halte ich für nett aber unrealistisch.

Ein Argument gegen selbstdokumentation: niemand ist in der Lage gute Namen zu wählen. Wenn man mal einen tollen Namen findet, gibt es garantiert einen anderen Entwickler für den der Name total unintuitiv ist.

 

[maki]

Ein Argument gegen selbstdokumentation: niemand ist in der Lage gute Namen zu wählen.

Halte ich für überzogen.
Einfach ist es nicht, aber man kann/sollte es üben.

Wenn man mal einen tollen Namen findet, gibt es garantiert einen anderen Entwickler für den der Name total unintuitiv ist.

Konventionen können helfen.

 

[tuxedo]

>> Aber jede Methode kann dazu refactored werden, und das ist genau der Punkt, wann ist Code "fertig"?
Wenn er funktioniert? Code zu schreiben der vom Compiler verstanden wird ist einfach, Code zu schreiben der vom Menschen verstanden wird ist die Kunst.
Wie gesagt, gemessen daran wie oft Code gelesen wird wird imho viel zuwenig auf die Struktur geachtet.

Den letzten Satz kann ich so unterschreiben. Das dumme ist nur: Der "Markt" bezahlt einem nicht den gut strukturierten Code. Viele Firmen stehen unter Zeitdruck. Das Produkt muss raus, muss verkauft werden. Sobald mal eine Release den Markt erreicht hat steht einem schon das Management im Nacken mit neuen Features und Funktionen. Zeitpläne sehen leider äusserst selten vor dass "alter" Code endlich mal ausgeräumt wird. Neue Features lassen sich eben besser verkaufen als einen nun aufgeräumten Code, der im Endeffekt nach wie vor das gleiche Feature liefert.

Ich heisse solchen Vorgehen nicht für gut, aber was will man machen? Letztendlich versuche ich schon bei der ersten Implementierung so sauber wie möglich zu arbeiten, so dass andere, welche den Code irgendwann mal in die Hand nehmen müssen, nicht die Hände über'm Kopf zusammenschlagen und denken "man, wer hat denn so nen Bockmist verbrochen".

>> Dieser Aufwand wäre beim Refactoring besser aufgehoben.

Kann ich zur hälfte unterschreiben. Nichts desto trotz bin ich davon überzeugt dass man manchen Stellen (ich sag jetzt einfach mal <=10% des Codes) ein Kommentar durchaus hilfreich sein kann und weder dem Code, noch dem Compiler, noch dem Management, was die Zeit, die für diesen kleinen Kommentar benötigt wird, bezahlen muss.

>> Du hattest gefragt

Kann ich mich nicht dran erinnern.

>> Wenn der Code sauber genug wäre, wären Kommentare so gut wie überflüssig, und genau das ist der Punkt.

Da haben wir's... "so gut wie" heisst nicht " in 100,00% der Fälle". Ich sag ja nicht - und das jetzt schon mehrfach - dass ich Code haben will der alle 5 Zeilen ein sinnloses Kommentar enthält. Nein. An verzwickten Stellen, und die gibt es auch nach dem refactoring hin und wieder macht es einfach Sinn eine Zeile erklärender Worte einzufügen. Nicht alle Gedankengänge lassen sich durch Code erklären. Aber viele. Und diese Differenz ist genau der Punkt wo ich sage: Her mit einem kleinen kommentar.

>> Die JRE/JDK Sourcen sind auch kein gutes Beispiel, zumindest meist.
War ja auch nur EIN Beispiel. Ich denke es gibt keinen Projekt das im Gesamtbild perfekt ist. Ausnahmen bestätigen eben die Regel ...

>> Früher war es gang und gäbe so viele Kommentare wie nur möglich einzufügen, mittlerweile hat sich (vor allem in OO Sprachen) diese Einstellung geändert.

Und ich sags jetzt zum x-ten mal: Kein Mensch will so viele Kommentare wie möglich. Auch das 70% Comment <-> 30% Code Paradigma was unter anderen an der UNI Karlsruhe "an den Mann gebracht wird" halte ich für nicht korrekt. Kommentare und dergleichen nur da wo sie Sinn machen und die Aussage des Codes nicht nochmal duplizieren. JavaDoc bei privaten Methoden muss nicht sein. Fertig.

- Alex

 

[Landei]

Stimme Tuxedo voll zu.

Beispiel Workarounds: Wenn ich etwa in der JMenuBar kein "richtiges" Hilfe-Menü setzen kann (weil Sun das seit Jahren nicht gebacken bekommt) und ich mich mit einem bisschen Box-Glue behelfe, dann ist das schon einen Kommentar wert (sonst denkt jemand in ein paar Jahren, ich wäre total bescheuert). Insbesondere der Verweis auf Bug-IDs kann sehr hilfreich sein.

Ansonsten: Nicht den cleversten Code programmieren ("Debuggen ist per definitionem doppelt so schwer wie schreiben, also kann ich meinen cleversten Code prinzipiell nicht debuggen"), das "Principle of Least Astonishment" beachten (und KISS und DRY und SoC :-) und immer überlegen, ob man jetzt an einer Stelle einen Kommentar macht oder lieber versucht zu vereinfachen.

 

[maki]

Den letzten Satz kann ich so unterschreiben. Das dumme ist nur: Der "Markt" bezahlt einem nicht den gut strukturierten Code. Viele Firmen stehen unter Zeitdruck. Das Produkt muss raus, muss verkauft werden. Sobald mal eine Release den Markt erreicht hat steht einem schon das Management im Nacken mit neuen Features und Funktionen. Zeitpläne sehen leider äusserst selten vor dass "alter" Code endlich mal ausgeräumt wird. Neue Features lassen sich eben besser verkaufen als einen nun aufgeräumten Code, der im Endeffekt nach wie vor das gleiche Feature liefert.

Ja, Refactoring (und Unittesting auch) wird noch nicht normale & integrale Tätigkeit beim Entwickeln angesehen, das Problem ist, dass wenn es nicht betrieben wird, neue Features immer länger dauern je mehr es bereits gibt.

Ich heisse solchen Vorgehen nicht für gut, aber was will man machen? Letztendlich versuche ich schon bei der ersten Implementierung so sauber wie möglich zu arbeiten, so dass andere, welche den Code irgendwann mal in die Hand nehmen müssen, nicht die Hände über'm Kopf zusammenschlagen und denken "man, wer hat denn so nen Bockmist verbrochen".

Tja, das einzig akzeptierte Masseinheit für Code-Qualität sind eben immer noch "WTFs per Minute"

Kann ich zur hälfte unterschreiben. Nichts desto trotz bin ich davon überzeugt dass man manchen Stellen (ich sag jetzt einfach mal <=10% des Codes) ein Kommentar durchaus hilfreich sein kann und weder dem Code, noch dem Compiler, noch dem Management, was die Zeit, die für diesen kleinen Kommentar benötigt wird, bezahlen muss.

Gut, 10% sind auch etwas ganz anderes als "Private Methoden nicht kommentieren? Wo gibts denn sowas?", letzteres impliziert nämlich das alle privaten Methoden kommentiert werden sollten.
Die Ausnahme sollte eben das Kommentar sein (nicht-JavaDoc), nicht die Regel.

Kann ich mich nicht dran erinnern.

siehe oben: "Private Methoden nicht kommentieren? Wo gibts denn sowas?"

Und ich sags jetzt zum x-ten mal: Kein Mensch will so viele Kommentare wie möglich.

Das hört sich oben noch ganz anders an

 

[SchonWiederFred]

Ich bin mittlerweile auch ein Gegner von Implementationskommentaren. Solange man sprechende Namen wählt, sollte es eigentlich keine Probleme geben.

Negativbeispiel in C++, ohne Kommentare fast unverständlich:

int random(int l, int u)
{
    return l + int(rand() * (1.0 / (RAND_MAX + 1.0)) * (u - l + 1));
}

Durch Umbenennung und Einführung sprechender lokaler Variablen viel besser verständlich:

int random_number_between(int lower, int upper)
{
    const double squeeze = 1.0 / (RAND_MAX + 1.0);
    int range = upper - lower + 1;
    return lower + int(rand() * squeeze * range);
}

Schnittstellenkommentare können manchmal sinnvoll sein, gerne mit typischem Beispiel:

// both bounds are inclusive
// random_number_between(1, 6) simulates a dice roll
int random_number_between(int lower, int upper)
{
    const double squeeze = 1.0 / (RAND_MAX + 1.0);
    int range = upper - lower + 1;
    return lower + int(rand() * squeeze * range);
}

 

[tuxedo]

Gut, 10% sind auch etwas ganz anderes als "Private Methoden nicht kommentieren? Wo gibts denn sowas?", letzteres impliziert nämlich das alle privaten Methoden kommentiert werden sollten.
Die Ausnahme sollte eben das Kommentar sein (nicht-JavaDoc), nicht die Regel.

Gut dass wir drüber geredet haben.. Deine Aussagen haben bei mir impliziert, dass private Methoden keinesfalls unter keinen Umständen und nie und nimmer Kommentiert werden sollten.

siehe oben: "Private Methoden nicht kommentieren? Wo gibts denn sowas?"

Ach so... Naja, das war eher eine Frage von der Art, die man nicht explizit beantwortet haben möchte

Alles in allem können wir uns also drauf einigen dass man da kommentieren sollte wo es angebracht ist und einen gewissen Mehrwert zum Code liefert und nicht "ausartet". Eine z.B. "setFrameWidth(int width)" Methode im body noch großartig zu kommentieren, dass damit die Fensterbreite gesetzt wird wäre doppelt gemoppelt. Da bin ich auch kein Freund von.

 

[maki]

Dann sind wir uns ja einig tuxedo

 

[tuxedo]

Und wieder ein "Problem" gelöst *freu*

- Alex