Java Klassen kommentieren?

[nettchen]

Hallo,

habe mal ne frage die mit dem direkten Programmieren eigentlich nix zu tun hat, sondern mit den Kommentaren für die JAVA Doc

Und zwar wie kommentiert man richtig? Also müssen alle Paramter auch dokumentiert sein, und muss bei methoden nur die Aufgabe dokumentiert werden oder auch wie die aufgabe gelöst wird

 

[nettchen]

Und da fällt mir gleich noch etwas ein müssen all get und set-Methoden kommentiert werden, habe in meiner einen Klasse nämlich fast 30 Parameter und da macht das eine heidenarbeit?

 

[Beni]

"Müssen" tuest du garnichts, aber je mehr Dokumentation desto besser.

Was die Klasse überhaupt sein soll, ist IMHO der wichtigste Kommentar. Den solltest du nicht übergehen.
Bei Methoden beschreibe ich nur das "was". Das "wie" ist selten wichtig (und das kann man zur Not auch im Quellcode nachschauen).
Argumente für Methoden würde ich unbedingt dokumentieren, später rauszufinden welches Argument was macht, ist extrem mühsam.
Setter: nutzt die Gelegenheit und beschreib für was die gesetzte Variable gut ist (was der Setter macht, ist jedem klar...).
Getter: ein Verweis auf den Setter, mehr nicht.

Und natürlich gibt es immer Ausnahmen... :wink:

 

[schalentier]

Tja, klare Regeln gibts da nicht. Liegt in deinem Ermessen...

ich versuch mich an: "Soviel wie noetig, sowenig wie moeglich" zu halten. Kommentare sollten erklaeren, warum und wozu die Methode oder der Parameter gebraucht wird. Das wie und was sollte in selbstklaerendem Quellcode auch ohne viel Geschafel erkennbar sein.

Bei Gettern und Settern musst du schauen, ob das selbstklaerend ist, oder nicht. Sinnlos ist in meinen Augen, wenn an 30 Getter/Settern immer steht: Setter fuer Name, Getter fuer Name, ...

Es gibt auch "radikale" Stimmen die behaupten, Kommentare sind in gutem Quellcode ueberfluessig, wenn die Namen von Methoden, Klassen und Parametern selbstklaerend gewaehlt sind. Wichtiger ist ein Dokument, in dem das Konzept erklaert wird, was im Normalfall mehrere Klassen betrifft. Ein guter Ansatz sind hier UML Diagramme.

 

[nettchen]

naja es ist halt für ne studienarbeit und da mein Prof zurezeit im Urlaub ist kann ich ihn nicht fragen, und dachte ich frag mal euch.

Wegen den Gettern und Settern bin ich mir noch am meißten unsicher, weil dadurch das die Klassen die ich aktuelle kommentiere nur Klassen zur Speicherng für Objekte dind, also nur aus Konstruktor und get bzw set methoden bestehen, finde ich es halt ein bischen sinnlos, jede get und set methode zu kommentieren, da ja wirklich nicht mehr drin steht als setzt Name auf neuen wert bei set und bei get lifert Name?

 

[Beni]

Sinnlos:

/*
 * Setzt den Namen
 * @param name Der Name
 */
public void setName( String name ){
  this.name = name;
}

Sinvoller:

/*
 * Der Name hat keine direkte Auswirkung auf die Logik, er
 * dient nur dem Benutzer zur Wiedererkennung des Objektes.
 * Entsprechend sind Namen wie "Heinz" oder "Fritz" kryptischen
 * Konstrukten wie "lbj4", "rgt86.h" vorzuziehen.
 * @param name der neue Namen, nicht null
 */
public void setName( String name ){
  this.name = name;
}

 

[nettchen]

ja und genau so wie du deinen sinnlos Kommentar aufgebaut hast sieht meiner aus, und wie du schon drüber geschrieben hast ist er total sinnlos, aber über jede get und set methode jetzt so nen langen Text zu schreiben, da sitz ich je in drei tagen noch dran wie gesagt , ich kommentiere erstmal nur die datenklassen für eine schnittstelle.
Mal sehen vielleciht erwisch ich ja aus der uni mal jemand den ich fragen kann was sich der professor gerne wünscht

Dank euch auf alle fälle schon mal , über eure erfahrung mit profs in bezug auf kommentare freu ich mich

 

[nettchen]

Hallo, habe mal ne Klasse kommentiert, habe die get und set methoden erst mal gelassen und nur den rest kommentiert, lest ihr das mal bitte und sagt ob das so ok ist, ich hab jetzt nicht so viel geschrieben, aber habe gerade erfahren das die kommentare in english sind, und hoffe es ist ausreichend.

import java.io.Serializable;
/**
 * This class is a response object for the method assignAttach.
 * 
 * The method assignAttach confirms the assignment of a attachment.
 * 
 * @author Janett Vollstädt
 * @version 1.0
 *
 */
public class AssignAttachResponse implements Serializable
{

	/**
	 * The serialID, this is for the correct serialisation and deserialisiation of the object
	 */
	private static final long serialVersionUID = 1L;
	
	/**
	 * The errorCode, this is the code for the error 
	 * 
	 * The code is 0, if no error has occurred 
	 */
	private int errorCode;
	
	/**
	 * The errorMessage, this text is the suited errorText for the errorCode 
	 * 
	 * The errorMessage is null, if the errorCode is null, because no error has occurred 
	 */
	private String errorMessage;
	
	/**
	 * Creates a new response object , with the with a errorCode and a errorMessage.	 * 
	 * 
	 * @param errorCode , the errorCode if a error has occurred , otherwise 0
	 * @param errorMessage, the errorMessage if a error has occurred , otherwise null
	 */
	public AssignAttachResponse(int errorCode, String errorMessage)
	{
		this.errorCode = errorCode;
		this.errorMessage = errorMessage;
	}

	public int getErrorCode()
	{
		return errorCode;
	}

	public String getErrorMessage()
	{
		return errorMessage;
	}

	public void setErrorCode(int errorCode)
	{
		this.errorCode = errorCode;
	}

	public void setErrorMessage(String errorMessage)
	{
		this.errorMessage = errorMessage;
	}
}

Also was meint ihr, ist das aktzeptabel, ich weiß das ich bei größeren Methoden mehr kommentieren muss, aber so für die datenklassen reicht das doch oder?

 

[mikachu]

das reicht

im eclipse weiß ich, dass man da autokommentare bei jeder methode zumindest einstellen kann, wie die aussehen etc... und was das so standardmäßig drin steht...
das gibts vll auch für klassenvariablen, weiß ich aber jezt nicht.

 

[nettchen]

also das habe ich auch verwendet also da steht dann halt sowas wie @author oder @param und so oder gibts da noch was anderes was man einstellen kann, das man mehr erhält

 

[nettchen]

Hat noch jemand ne idee wie ich errorcode und errormessage kommentieren könnte, also der errorcode ist der fehlercode und die errormessage logischerweise der dazugehörige text, aber kann ich das so einfach dahinterschreiben?

 

[Philip]

Also dass "errorMessage" die "error message" ist, finde ich nicht erwähnenswert.
Schreib doch lieber genauer, was der errorCode darstellen soll. Wenn es ein Code ist, wie wird er decodiert? Hast du da irgendeine Tabelle mit bekannten ErrorCodes oder sowas? Vielleicht dass der errorCode dem HTTP-Statuscode entspricht oder sonst irgendeinem bekannten Standard. Oder eine eigene Aufschlüsselung, wenn es ein eigener Code ist.

Oder wie soll der errorCode in der Anwendung zum Tragen kommen? Was für einen Zweck hat er? Wann treten diese Errors auf, usw?


Aber zu deiner Beruhigung: ich schreib auch oft so einen Satz in die Doku, der eigentlich überflüssig wäre, weil selbstredende Parameternamen schon alles gesagt haben. Trotzdem muss der Kommentar aus meiner Sicht einen Mehrwert an Information liefern. Sonst ist er überflüssig und macht nur den Quellcode unübersichtlicher.

Z.B. ein aktuelles Beispiel:

Ich habe eine Klasse, die hat u.a. die Attribute "id", "name" und "title". Da fand ich es z.B. wichtig zu beschreiben, wie sich die Attribute voneinander abgrenzen.
"id" ist nur ein internes Attribut, um Instanzen eindeutig voneinander unterscheiden zu können und sicht nicht zur Ausgabe an der Oberlfäche gedacht, schon gar nicht darf der User die id irgendwie ändern.
"name" ist der benutzerfreundliche Name, nur zur Darstellung der Instanz auf der Oberfläche gedacht
Und das Attribut "title" gehört zur Anwendungslogik.

 

[NTB]

Mach Dir beim Schreiben der Kommentare bewusst, wofür sie da sind. Im Moment wirkt es so, dass Du die Kommentare reinschreibst, weil der Prof das nunmal erwartet.

Die Kommentare sollen fremden Programmierern helfen, sofort Deinen Quelltext verstehen zu können. Spätestens nach vier Wochen gehörst Du übrigens auch zu den fremden Programmierern, weil Du nicht mehr weisst, was Du da eigentlich verzapft hast

Also versetz Dich in die Lage anderer: Sie müssen beim Lesen verstehen, was Dein Code macht. Genau dann sind die Kommentare gut.

Für Deinen Prof kannst Du dann noch über die getter und setter Kommentare einfügen. Da würde ich glaube ich einfach "Setter" und "Getter" als Kommentar einfügen. Dann ist klar, dass keine Logik hinter steckt.

 

[nettchen]

Da hast du nicht ganz unrecht, weil ich moment ja auch nur datenklassen kommentiere, die halt keine wichtigen Methoden haben und die namen der atttribute finde ich aussagekräftig, wenn ich dann bei den logikklassen bin werde ich das ganze ach etwas ausführlicher machen, bloß diese Klassen hier kommentiere ich nur weil ich muss.