Eure besten Quellcode Kommentare...

[Valle]

Kommentare können durchaus äußerst sinnlos werden.

An meiner Uni gibt es bei der Abgabe der Aufgaben zur Programmieren-Vorlesung eine automatische Überprüfung auf Stil und Kommentierung. Das endet dann in solchen Stilblüten, damit der Automat fehlerfrei durchläuft:

(Dabei sei hervorgehoben, dass nicht nur die Kommentierung jedes einzelnen Enum-Elements sinnlos ist, sondern auch diese inline-Versionierung und Angabe des Autors. Was um Himmels Willen soll der Quatsch denn?!)

Code:

/**
 * Eine einfache Definition eines Wochentags.
 * @version 1.0
 * @author Valentin Voigt
 */

enum Weekday {
   
   /**
    * Sonntag   
    */
   
   SUNDAY,
   
   /**
    * Montag
    */
   
   MONDAY,
   
   /**
    * Dienstag
    */
   
   TUESDAY,
   
   /**
    * Mittwoch
    */
   
   WEDNESDAY,
   
   /**
    * Donnerstag
    */
   
   THURSDAY,
   
   /**
    * Freitag
    */
   
   FRIDAY,
   
   /**
    * Samstag
    */
   
   SATURDAY
}

[Mikkey]

[QUOTE=himitsu;1239686]

Zitat:

Zitat von p80286 (Beitrag 1239685)

Wobei der Kommentar nichts doppelt sinnlos erklärt, sondern das shr erklärt.

Sinnlos is m.E. eher die Anweisung selbst. Wenn ich durch zwei teilen will (was laut Kommentar ja die Absicht ist), dann sollte ich das auch so schreiben;

Code:

a := b div 2;

Optimierung im Algorithmus mag ja sinnvoll sein, aber ob eine Shift-Operation schneller als die Teilungsoperation ist, sollte man dem Compiler überlassen.

Es mag aber durchaus geeignetere Beispiele geben, wo diese Art von Kommentar sinnvoll ist.

[Furtbichler]

Zitat:

Zitat von Tonic1024 (Beitrag 1239681)

Zitat:

Zitat von r2c2 (Beitrag 1239639)

Das ist ein Zeichen dafür, dass deine Methoden zu lang sind.

Das ist reine Theorie.

Eher das Ergebnis jahrelanger Erfahrung professioneller Programmierer auf der ganzen Welt.

Zitat:

Wenn man zum Beispiel einem Webserver einige Aufgaben gibt...

Dann ruft man die Methode einer Klasse auf.

Zitat:

Ich wundere mich warum hier so eine Abneigung gegen Kommentare mit optischem Charakter herrscht. Ich hab noch beigebracht bekommen über jede Routine einen Funktionsbeschreibung, Parameterdefinition, Precondition und Postcondition zu tippen.

Na ja, Optik...:roll: Wieso nicht gleich mit Blümchen ausschmücken. Public-Methoden einer API ja, sonst ist das imho überflüssig.

Lies mal 'Pragmatic Programmer' oder 'Clean Code'. Dann wirst Du vielleicht erkennen, das Kommentare, bis auf wenige Ausnahmen, schlecht sind und den Code auf Dauer unleserlich machen. Was heute noch ein korrekter Kommentar wird, ist morgen veraltet, weil -wupps wegen Zeitmangel- der Kommentar nicht angepasst wurde.

Ausnahmen sind z.B.: Gesetzliche Vorschriften, Quellenangaben, mathematische Formeln und API-Dokumentation (in Zeiten von Code Proposal und automatisch generierter Hilfe aus Methoden-Kommentaren durchaus akzeptabel).

Dessenungeachtet und schon 1000x gesagt: Wer seinen Code kommentieren muss, hat wohl schwer verständlichen Code. Wer Parameter beschreiben muss, hat wohl schlecht gewählte Parameterbezeichnungen.

Umgekehrt: Wer kleine Methoden schreibt, die genau eine Sache machen (die sich also ohne das Wort 'und' beschreiben lassen), dann hat man den Code durch sich selbst dokumentiert: Er ist also lesbar, automatisch leichter wartbar und -weil verständlich und einfach- auch robuster.

Aber klar, man kann auch 100 Zeilen lange Monster schreiben und glücklich werden, fragt sich nur, wie lange. Ich überlege schon bei 10 Zeilen, ob ich nicht refaktorisieren kann (und mach das meistens auch).

Aber hier gehts um lustige Quelltextkommentare, nicht um Codestil.

[Namenloser]

Zitat:

Zitat von Valle (Beitrag 1239688)

Kommentare können durchaus äußerst sinnlos werden.

An meiner Uni gibt es bei der Abgabe der Aufgaben zur Programmieren-Vorlesung eine automatische Überprüfung auf Stil und Kommentierung. Das endet dann in solchen Stilblüten, damit der Automat fehlerfrei durchläuft:

(Dabei sei hervorgehoben, dass nicht nur die Kommentierung jedes einzelnen Enum-Elements sinnlos ist, sondern auch diese inline-Versionierung und Angabe des Autors. Was um Himmels Willen soll der Quatsch denn?!)

Der Code hat mich gleich an die Programmieren-Vorlesung hier erinnert... dann ist mir aufgefallen, dass du ja auch in Karlsruhe studierst :oops:

Als ich das erste (und letzte ;)) mal im Programmieren-Tutorium war und der Tutor uns zeigte, wie man jedes einzelne Klassenmember mit einem dreizeiligen Kommentar versehen soll, dachte ich erst, es wäre ein Scherz :roll:

Naja, aktuell mache ich hier dieses Softwarepraktikum (nicht am KIT), und da ist jetzt von den Coding Conventions gefordert, zwischen alle Funktionsdefinitionen solche Trennlinien zu machen:

Delphi-Quellcode:

//============================================================================

Auch sehr sinnlos... wobei der Rest recht vernünftig ist, das macht es für mich noch irritierender.

[Meflin]

Zitat:

Zitat von Namenloser (Beitrag 1239714)

Naja, aktuell mache ich hier dieses Softwarepraktikum (nicht am KIT), und da ist jetzt von den Coding Conventions gefordert, zwischen alle Funktionsdefinitionen solche Trennlinien zu machen:

Delphi-Quellcode:

//============================================================================

Wie dumm ist das denn? Vor allem, wenn man bedenkt, dass ein durchschnittlicher Editor sowas heutzutage von selbst einfügen anzeigen kann, sofern man es denn haben will :roll:

[Namenloser]

Ja, hab ich denen auch gesagt, dass ich das für eine Aufgabe des Syntax-Highlighting halte... aber was will man machen.

[himitsu]

Ein sehr gutes Beispiel für gute, hilfreiche und nützliche Kommentare, denn ohne diese wüsste man ja garnicht, was da gemacht wird.

PHP-Quellcode:

// read the step get variable
if(isset($_GET['step'])) $step=$_GET['step']; else $step=0;

// show the header
oc_setup::showheader();

...

// show the footer
oc_setup::showfooter();

[Memnarch]

Zitat:

Zitat von Mikkey (Beitrag 1239689)

Code:

a := b div 2;

Optimierung im Algorithmus mag ja sinnvoll sein, aber ob eine Shift-Operation schneller als die Teilungsoperation ist, sollte man dem Compiler überlassen.

Yep, ein shr ist in dem Fall schneller als ein DIV. Liegt daran, das eine DIV-Operation(welche direkt in der CPU integriert ist) sehr aufwendig ist, da sie im allgemeinen an das mathematische Problem rangeht.(von +-*/ ist / bzw DIV die langsamste)

mit shr nimmst du bei Dvisionen durch eine Zweierpotenz(2, 4, 8, 16) eine unkomplizierte Abkürzung. ein shr ist vergleichweise schnell erledigt auf der CPU. Die logik dahinter ist einfach unkomplizierter.

EDIT: Und falls jemand fragt: Nein, in einer normalen Anwendung ist das komplett Hupe, ob man div oder shr nimmt(hier würde ich der Lesbarkeithalber eher div empfehlen). Aber mein Softwarerenderer hat's mir gedankt ;)

Grüße
Memnarch

[Mikkey]

@Memnarch: Sei mir nicht böse, aber ein Compiler, der nicht selbst ein "... div 2" durch "... SHR 2" ersetzt (wenn die Ziel-CPU denn damit auch wirklich schneller ist), gehört in die Tonne.

[himitsu]

Wobei Delphi bei einem Unsigned Integer das

Delphi-Quellcode:

DIV (2^x)

und

Delphi-Quellcode:

* (2^x)

entsprechend in ein SHR/SHL optimiert.
> wenn rechts eine Konstante ist
> wenn rechts eine 2er-Potenz steht
> wenn links kein Vorzeichen drin ist