Quellcodekommentierung

[SeTHVision]

Hallo Ihr da drausem im WWW,

als erstes noch einmal riesen Danke für die positiven Rückmeldungen bei meinem Projektantrag mittlerweile ist er auch bei meiner zuständigen IHK über die Schreibtische des PAs gewandert und wurde als ausreichend befunden.

Was für mich heißt ran an die Arbeit, jetzt meine eigentliche Frage wie sollte man das mit der Kommentierung der Quelltexte handhaben, ganz nach dem Motto "weniger ist mehr" oder doch "lieber zu viel als zu wenig"?

Hier mal ein die Beschreibun einer Funktion einer von mir erstellten Klasse ist das so ok, zu wenig oder zu übertrieben?

//////////////////////////////////////////////////////////////////////////////

// Autor: Marco Arbitter

//

// Beschreibung:

// Konvertiert und verknüpft die einzelnen Elemente fuer Dateipfad und

// Dateiname zu einem String.

//

// Eingangsparameter:

// Datum : HDINT | Datum mit dem Format DD.MM.YYYY

// Uhrzeit : HDINT | Uhrzeit mit dem Format HH:MM:SS

// File : DINT | Kann den Wert 0 fuer Logfile oder 1 fuer Konfigfile haben

// Pfad : ^void | Enthaellt die Pfadkonstante Bsp.: "C:\"

// Endung : ^void | Enthaellt die Dateiendung Bsp.: "*.csv" oder "*.txt"

//

// Ausgangsparameter:

// Result : SINT | Resultierender Dateipfad

//////////////////////////////////////////////////////////////////////////////

Schon mal vielen Dank in vorraus.

Greetz

Marco

[Abd Sabour]

In welcher Sprache schreibst du deinen Quelltext ? Denn in Java hält man sich eigentlich an die Javadoc-Konventionen, ein Beispiel:

/**

 * @author yourNameHere

 * 

 * Per source file you may have multiple classes declared but only one of them

 * as public.

 * 

 */

public class JavaranchOne {


        /**

        *Stores the name of the ranch.

        */

	private String myRanch;


	/**

	 * Method returns the version number for the corresponding item.

         *

	 * @return a String representing the version

	 */

	public static String getVersion() {

		return version;

	}


}

Schau dich ruhig mal hier um: Java Platform SE 6 - ein gutes Beispiel wie mans (zumindest in Java) macht . Zu anderen Sprachen kann ich leider nicht viel sagen ...

[SeTHVision]

Ich verwende eine SPS eigene Objektorientierte Programmiersprache mit dem namen LASAL. Eigentlich gehts mir auch nicht wirklich um die art der Kommentierung oder um die Syntax sondern eher um die ausführlichkeit der Kommentierung

[Abd Sabour]

Ich verwende eine SPS eigene Objektorientierte Programmiersprache mit dem namen LASAL. Eigentlich gehts mir auch nicht wirklich um die art der Kommentierung oder um die Syntax sondern eher um die ausführlichkeit der Kommentierung

Mhh von der Ausführlichkeit her fände ich es in Ordnung - bei größeren/komplexeren Methoden ist es allerdings auch sinnvoll innerhalb der Methode bestimmte Abläufe zu kommentieren. Allerdings sollte man eher eindeutige/selbsterklärende Variablennamen verwenden statt zuviele Kommentare. Denn aus Erfahrung (und da werden mir sicher einige zustimmen) kann ich sagen: Code wird schnell mal geändert, die Kommentare werden allerdings oft nicht angepasst und stimmen dann nicht mehr mit dem Code überein was zu ordentlicher Verwirrung führen kann wenn sich jemand anders mal in den Quellcode einarbeiten muss. Ist mir selbst schon passiert und fabriziert hab ich sowas auch schon des öfteren .

[SeTHVision]

Ok vielen dank für das Statement sowas in der art hatte ich auch vor dann bin ich ja auf dem richtigen weg

[allesweg]

Sourcekommentierung ist nur dann von Interesse, wenn du deine Sourcen abgeben wirst. Wie ausführlich man kommentiert hängt von der Komplexität des Codes und dessen "Gesprächigkeit" ab.

Ich empfehle generell, entweder deutsche oder englische Begriffe zu verwenden und nicht ins gemischte Denglisch zu verfallen.

[SeTHVision]

ok danke für den comment, ja von mir wird verlangt meinen SC in 6 facher ausfertigung mit der doku ab zu geben

[Kaladhor]

Wenn man zusieht, dass man seinen Sourcecode nicht zu komplex erstellt, kann man sich nahezu jeden Kommentar sparen. Konsequente Verwendung "sprechender" Attributnamen, Konsequente Anwendung vorher definierter Codestyles machen sehr viele Kommentare überflüssig.

Am Ende kann man dann, zumindest in Java, hergehen, und entsprechende Javadoc-Kommentare einfügen (bei allen Methoden ausser get/set). Das ist aber auch nur sinnvoll, wenn ich die Klassen hinterher als "Black Boxes" verwenden möchte.

Ich arbeite derzeit an einem Projekt mit, das schätzungsweise 10.000 Klassen beinhaltet. Dort wird konsequent nach der von mir oben beschrieben Methodik entwickelt. Zusätzlich gilt der ungeschriebene Leitsatz: "Alles, was zusätzlich kommentiert werden muß, wird in eine eigene Methode ausgelagert."

Das Ergebnis ist ein Sourcecode von sehr hoher Qualität, der Dank diverser Code Reviews nahezu fehlerfrei beim Kunden live geht.

[Abd Sabour]

Wenn man zusieht, dass man seinen Sourcecode nicht zu komplex erstellt, kann man sich nahezu jeden Kommentar sparen. Konsequente Verwendung "sprechender" Attributnamen, Konsequente Anwendung vorher definierter Codestyles machen sehr viele Kommentare überflüssig.

Am Ende kann man dann, zumindest in Java, hergehen, und entsprechende Javadoc-Kommentare einfügen (bei allen Methoden ausser get/set). Das ist aber auch nur sinnvoll, wenn ich die Klassen hinterher als "Black Boxes" verwenden möchte.

Ich arbeite derzeit an einem Projekt mit, das schätzungsweise 10.000 Klassen beinhaltet. Dort wird konsequent nach der von mir oben beschrieben Methodik entwickelt. Zusätzlich gilt der ungeschriebene Leitsatz: "Alles, was zusätzlich kommentiert werden muß, wird in eine eigene Methode ausgelagert."

Das Ergebnis ist ein Sourcecode von sehr hoher Qualität, der Dank diverser Code Reviews nahezu fehlerfrei beim Kunden live geht.

Ähm Setter und Getter haben sehr wohl javadoc Kommentare:

Java Platform SE 6

Javadoc ist alles das, was bei einer doc-Generierung mit aufgenommen wird - hierzu gehören u.a. solche Kommentare: /** */ und die gibts zumindest in der Java API für jede setter und getter Methode ....

Und deine letzte Theorie find ich schon etwas merkwürdig ? Nur weil ich alles in tausend Mini-Methoden auslagere wirds doch nicht besser ? Logikfehler können immernoch drin sein und ich halt es für fraglich ob massig kleine Methoden einfacher zu warten sind als 10 größere .... Leitsatz ist hingegen folgender: Eine Methode sollte im Idealfall auf den PC-Monitor passen (damit man die ganze Methode im Blick hat ohne zu scrollen).

[Kaladhor]

Doch, es ist wesentlich einfacher, mehrere kleine Methoden zu warten, als ein paar Größere. Stichwort Komplexität. Gerade Logikfehler sind so wesentlich einfacher und schneller zu finden, als wenn man gezwungen ist hochkomplexe Methoden zu "untersuchen".

Im übrigen gilt bei uns grundsätzlich für jede Methode <50 LoC.

Im übrigen ist es widersinnig, get/set-Methoden zu kommentieren, weil es einfach nur Schnittstellen zu den Attributen einer Klasse sind.

[Abd Sabour]

Im übrigen ist es widersinnig, get/set-Methoden zu kommentieren, weil es einfach nur Schnittstellen zu den Attributen einer Klasse sind.

Nun - erzähl das mal SUN Microsystem .... die finden es offenischtlich nicht widersinnig ...