Sinnvolles kommentieren

[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.