接口的代碼是否應該包含註釋？

Question

Java接口是否應該在其源代碼中包含任何註釋，或者只是實現接口（或兩者）的類？

實施例：

public interface Book{ 
     /** 
     * Commentaries should be here? 
     */ 
     void read(); 
} 

public class Book{ 
     /** 
     * Commentaries should be here? 
     */ 
     void read(); 
} 

感謝。

Answer 1

應該記錄一個Java接口。文檔貫穿到實現接口的具體類中。

下面是記錄界面的一個很好的例子。這些是從List interface開始的評論。評論不僅描述了界面的功能，還描述了界面不做的事情。

我們都應該努力寫下這樣的評論。

/** 
* An ordered collection (also known as a <i>sequence</i>). The user of this 
* interface has precise control over where in the list each element is 
* inserted. The user can access elements by their integer index (position in 
* the list), and search for elements in the list.<p> 
* 
* Unlike sets, lists typically allow duplicate elements. More formally, 
* lists typically allow pairs of elements <tt>e1</tt> and <tt>e2</tt> 
* such that <tt>e1.equals(e2)</tt>, and they typically allow multiple 
* null elements if they allow null elements at all. It is not inconceivable 
* that someone might wish to implement a list that prohibits duplicates, by 
* throwing runtime exceptions when the user attempts to insert them, but we 
* expect this usage to be rare.<p> 
* 
* The <tt>List</tt> interface places additional stipulations, beyond those 
* specified in the <tt>Collection</tt> interface, on the contracts of the 
* <tt>iterator</tt>, <tt>add</tt>, <tt>remove</tt>, <tt>equals</tt>, and 
* <tt>hashCode</tt> methods. Declarations for other inherited methods are 
* also included here for convenience.<p> 
* 
* The <tt>List</tt> interface provides four methods for positional (indexed) 
* access to list elements. Lists (like Java arrays) are zero based. Note 
* that these operations may execute in time proportional to the index value 
* for some implementations (the <tt>LinkedList</tt> class, for 
* example). Thus, iterating over the elements in a list is typically 
* preferable to indexing through it if the caller does not know the 
* implementation.<p> 
* 
* The <tt>List</tt> interface provides a special iterator, called a 
* <tt>ListIterator</tt>, that allows element insertion and replacement, and 
* bidirectional access in addition to the normal operations that the 
* <tt>Iterator</tt> interface provides. A method is provided to obtain a 
* list iterator that starts at a specified position in the list.<p> 
* 
* The <tt>List</tt> interface provides two methods to search for a specified 
* object. From a performance standpoint, these methods should be used with 
* caution. In many implementations they will perform costly linear 
* searches.<p> 
* 
* The <tt>List</tt> interface provides two methods to efficiently insert and 
* remove multiple elements at an arbitrary point in the list.<p> 
* 
* Note: While it is permissible for lists to contain themselves as elements, 
* extreme caution is advised: the <tt>equals</tt> and <tt>hashCode</tt> 
* methods are no longer well defined on such a list. 
* 
* <p>Some list implementations have restrictions on the elements that 
* they may contain. For example, some implementations prohibit null elements, 
* and some have restrictions on the types of their elements. Attempting to 
* add an ineligible element throws an unchecked exception, typically 
* <tt>NullPointerException</tt> or <tt>ClassCastException</tt>. Attempting 
* to query the presence of an ineligible element may throw an exception, 
* or it may simply return false; some implementations will exhibit the former 
* behavior and some will exhibit the latter. More generally, attempting an 
* operation on an ineligible element whose completion would not result in 
* the insertion of an ineligible element into the list may throw an 
* exception or it may succeed, at the option of the implementation. 
* Such exceptions are marked as "optional" in the specification for this 
* interface. 
* 
* <p>This interface is a member of the 
* <a href="{@docRoot}/../technotes/guides/collections/index.html"> 
* Java Collections Framework</a>. 
* 
* @param <E> the type of elements in this list 
* 
* @author Josh Bloch 
* @author Neal Gafter 
* @see Collection 
* @see Set 
* @see ArrayList 
* @see LinkedList 
* @see Vector 
* @see Arrays#asList(Object[]) 
* @see Collections#nCopies(int, Object) 
* @see Collections#EMPTY_LIST 
* @see AbstractList 
* @see AbstractSequentialList 
* @since 1.2 
*/