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();
	
}