Sinnvolles kommentieren

[bubble]

Hi,

das Kommentare/Dokumentationen sehr wichtig sind merk man, sobald man zum ersten Mal Code von jemand anderem verwendet, bisher habe ich immer nur notdürftig was kommentiert, was meist darin endete, dass, wenn ich die Klasse ein paar Monate später verwenden wollte, ich nicht mehr wirklich wusste, was eine Methode wirklich machen soll. Da ich mich in letzter Zeit mit OSGi beschäftige und ich es ordentlich machen möchte habe ich mal ein Interface deklariert und kommentiert und möchte euch fragen, ob das so verständlich/richtig ist bzw. generelles Feedback erhalten.

Danke schon mal im Voraus, mfG bubble

/**
 * A container for data of a specific type.
 * 
 * A buffer is a linear sequence of elements without a capacity limit.
 * All methods have to be thread safe.
 * 
 * @author bubble
 *
 * @param <T> Type of data the buffer stores.
 */
public interface Buffer<T> {
	
	/**
	 * Resets the buffer.
	 * 
	 * The buffer must not contain any data and have a size of 0 (zero) after this call.
	 */
	public void clear();
	/**
	 * Removes a specified number of elements from the head of the buffer.
	 * 
	 * @param length Specified number of elements to remove.
	 */
	public void clear(int length);
	
	/**
	 * Copies the head of the buffer into an destination array so it is filled.
	 * 
	 * The length of the destination array defines how many elements are copied. The buffer's content and size will not change.
	 * 
	 * @param data Destination array.
	 * @throws BufferUnderflowException Is thrown, if the destination array is bigger than the buffers content.
	 */
	public void peek(T[] data) throws BufferUnderflowException;
	/**
	 * Copies a specified number of elements from the head of the buffer into an destination array.
	 * 
	 * The buffer's content and size will not change.
	 *  
	 * @param data Destination array.
	 * @param length Number of elements to copy.
	 * @throws BufferUnderflowException Is thrown, if the specified length is bigger than the buffers content.
	 * @throws ArrayIndexOutOfBoundsException Is thrown, if the specified length is bigger than the destination array length.
	 */
	public void peek(T[] data, int length) throws BufferUnderflowException, ArrayIndexOutOfBoundsException;
	
	/**
	 * Cuts the head of the buffer into an destination array so it is filled.
	 * 
	 * The length of the destination array defines how many elements are copied.
	 * 
	 * @param data Destination array.
	 * @throws BufferUnderflowException Is thrown, if the destination array is bigger than the buffers content.
	 */
	public void pop(T[] data) throws BufferUnderflowException;
	/**
	 * Cuts a specified number of elements from the head of the buffer into an destination array.
	 *  
	 * @param data Destination array.
	 * @param length Number of elements to copy.
	 * @throws BufferUnderflowException Is thrown, if the specified length is bigger than the buffers content.
	 * @throws ArrayIndexOutOfBoundsException Is thrown, if the specified length is bigger than the destination array length.
	 */
	public void pop(T[] data, int length) throws BufferUnderflowException, ArrayIndexOutOfBoundsException;
	
	/**
	 * Appends a copy of the given data to the buffer.
	 * 
	 * @param data Data to append to the buffer.
	 * @throws BufferUnderflowException Is thrown, if the destination array is bigger than the buffers content.
	 */
	public void push(T[] data);
	/**
	 * Appends the first elements of the given data to the buffer.
	 * 
	 * @param data Source array of the elements to append to the buffer.
	 * @param length Number of elements to be appended.
	 * @throws ArrayIndexOutOfBoundsException Is thrown, if the specified length is bigger than the source array length.
	 */
	public void push(T[] data, int length) throws ArrayIndexOutOfBoundsException;
	
	/**
	 * Getter for the current buffer size.
	 * 
	 * @return Number of elements stored in the buffer.
	 */
	public int size();
	
}

[pl]

Also ich verstehe die Kommentare nicht. Gehe aber davon aus, dass sie zum Code passen.

[pl]

Also ich verstehe die Kommentare nicht. Gehe aber davon aus, dass sie zum Code passen.

Beispiel aus meiner Kiste (Formularverarbeitung)

else{ 
    # In diesem Block werden die Eingaben gespeichert
    # also hier sind alle Pflichtfelder ausgefüllt

    # Abschnitte im Template umschalten
    $self->{STASH}{pending} = 0;
    $self->{STASH}{complete} = 1;

    # Link für die Vorschau ins Template setzen
    $self->{STASH}{href} = qq($self->{URL}?show=$self->{STASH}{lfdnr});

    # Upload, die Bilder kriegen einfach die laufende Nummer
    # $self->{STASH}{lfdnr}) ist hier schon zugewiesen
    # $updata ist eine Referenz auf alle Daten des hochgeladenen Image
    # wenn ein Uplaod anhängig ist
    if(my $updata = $self->param('image') ){
        my $fh = IO::File->new;
        my $filename = $self->eav('uploaddir').'/'.$self->{STASH}{lfdnr};
        $fh->open($filename, O_RDWR|O_CREAT|O_BINARY|O_TRUNC) or die $!;
        seek($updata->{iohandle}, 0,0);
        read($updata->{iohandle}, my $binary, $updata->{content_length});
        $fh->print($binary);
        $fh->close;
    }

    # Daten persistent in DAL (Data Access Layer) machen
    # Attribut {DAL} wird in sub init{} aggregiert
    # Alle Formulareingaben liegen in %hunt
    $hunt{time} = time; # Zeitstempel einfügen
    $self->{DAL}->checkin($self->{STASH}{lfdnr}, %hunt) or die $@;
    $self->{DAL}->write or die $@;
}

[dedlfix]

Tach!

das Kommentare/Dokumentationen sehr wichtig sind merk man, sobald man zum ersten Mal Code von jemand anderem verwendet, bisher habe ich immer nur notdürftig was kommentiert, was meist darin endete, dass, wenn ich die Klasse ein paar Monate später verwenden wollte, ich nicht mehr wirklich wusste, was eine Methode wirklich machen soll. Da ich mich in letzter Zeit mit OSGi beschäftige und ich es ordentlich machen möchte habe ich mal ein Interface deklariert und kommentiert und möchte euch fragen, ob das so verständlich/richtig ist bzw. generelles Feedback erhalten.

• A container for data of a specific type.

Als Kurzbeschreibung zu allgemein. Eigentlich ist ja alles ein Container, selbst einfache Variablen. Diese erste Zeile wird ja meist beim Draufzeigen in der IDE angezeigt und sollte den Leser über den Verwendungszweck ins Bild setzen. Man weiß normalerweise als nicht gerade blutiger Anfänger um solche grundlegenden Dinge der Sprache, dass man Generics dafür verwendet, etwas abstrakt zu formulieren, das später mit einem konkreten Typ zu gemacht werden soll.

• A buffer is a linear sequence of elements without a capacity limit.

Aber wofür ist er vorgesehen? Gibt es für den hier angegebenen Zweck nicht schon Listen?

• @param <T> Type of data the buffer stores.

Allgemeinplatz. Wenn ein Doku-Mechanismus einen zwingt, etwas zu beschreiben, was eigentlich offensichtlich ist, kommen solche offensichtlichen Dokumentationen raus, die keinem einen Erkenntnisgewinn bringen, aber Arbeit verursacht haben. Gibt es irgendwelche Besonderheiten zu erwähnen? Das wäre interessant und sinnvoll, sowas zu dokumentieren.

• Resets the buffer.

Clear resets the buffer? Reset heißt zurücksetzen. Das heißt auf einen bestimmten Ursprungsstand bringen. Das muss ja nicht zwangsläufig "leer" bedeuten. Clear nimmt man aber meist, um etwas zu leeren, also sollte die Beschreibung auch genau das aussagen. "Removes all elements from the buffer."

• The buffer must not contain any data and have a size of 0 (zero) after this call.

"Must not contain" klingt nach einer Aufforderung an den Programmierer, der das Interface implementiert. Ein Interface sollte aber eher beschreiben, was der Verwender damit tun kann. Daraut kann der Implementierer auch schon lesen, was er zu implementieren hat. Wenn ein Verwender dies liest, kann es sein, dass er sich fragt, ob er was tun muss, bevor er diese Methode aufrufen darf.

Wenn ich das mal übergenau lese, sehe ich, dass diese Methode gar nichts macht: Der Buffer muss leer sein und ist es hinterher auch. (zudem: has statt have)

public void clear(); /**

• Removes a specified number of elements from the head of the buffer.

Start oder beginning oder top, aber head ist nicht nur die Spitze oder eine Anzahl Elemente an dieser, sondern ein komplexes Gebilde am oberen Teil.

• @param length Specified number of elements to remove.

Das "spezified" ist irgendwie komisch/redundant.

• Copies the head of the buffer into an destination array so it is filled.

"Copies as much elements from the top of the buffer to the destination array as it can hold" würde ich wohl eher schreiben.

Der Rest ist ja mehr oder weniger Wiederholung, oder mir fällt nichts bemeckerbares auf.

dedlfix.

[MudGuard]

Hi,

* The buffer must not contain any data and have a size of 0 (zero) after this call.

[...]

(zudem: has statt have)

Nein, have ist richtig. "must" wird mit Infinitiv benutzt.
Gemeint ist "must not contain [...] and must have"
Wobei das zweite must wegfallen darf.

cu,
Andreas a/k/a MudGuard

[woodfighter]

Tach,

• @param <T> Type of data the buffer stores.

Erklärt sich das durch die Verwendung von Generics nicht schon selbst? Und ist @param nicht eh nur für Methoden definiert?

public interface Buffer<T> {

Ein Buffer-Interface? Tun's die vorhandenen Buffer nicht?

/**

• Resets the buffer.
• The buffer must not contain any data and have a size of 0 (zero) after this call. */

Wenn du das hier umformulierst, kannst du es dir sparen in den implementierten Klassen den Kommentar wieder zu überschreiben; für den Nutzer der Klasse ist es relevant, dass der Buffer hinterher leer ist (nicht sein sollte), der Implementierende kann aus dem selben Kommentar aber die für ihn nötige Information rausziehen: „After this call the buffer does not contain any data and has a size of 0 (zero)“.

• Copies the head of the buffer into an destination array so it is filled.

into a destination

mfg
Woodfighter