Effective Java 62 Document all exceptions thrown by each method
2014-04-26 21:03
399 查看
Principle
Always declare checked exceptions individually, and document precisely the conditions under which each one is thrown using the Javadoc @throws tag.
A well-documented list of the unchecked exceptions that a method can throw effectively describes the preconditions for its successful execution.
It is particularly important that methods in interfaces document the unchecked exceptions they may throw. This documentation forms a part of the interface's general contract and enables common behavior among multiple implementations of the interface.
Use the Javadoc @throws tag to document each unchecked exception that a method can throw, but do not use the throws keyword to include unchecked exceptions in the method declaration.
If an exception is thrown by many methods in a class for the same reason, it is acceptable to document the exception in the class's documentation comment rather than documenting it individually for each method. (e.g. All methods in this class throw a NullPointerException if a null object reference is passed in any parameter," or words to that effect.)
Summary
Document every exception that can be thrown by each method that you write. This is true for unchecked as well as checked exceptions, and for abstract as well as concrete methods. Provide individual throws clauses for each checked exception and do not provide throws clauses for unchecked exceptions. If you fail to document the exceptions that your methods can throw, it will be difficult or impossible for others to make effective use of your classes and interfaces.
Always declare checked exceptions individually, and document precisely the conditions under which each one is thrown using the Javadoc @throws tag.
A well-documented list of the unchecked exceptions that a method can throw effectively describes the preconditions for its successful execution.
It is particularly important that methods in interfaces document the unchecked exceptions they may throw. This documentation forms a part of the interface's general contract and enables common behavior among multiple implementations of the interface.
Use the Javadoc @throws tag to document each unchecked exception that a method can throw, but do not use the throws keyword to include unchecked exceptions in the method declaration.
If an exception is thrown by many methods in a class for the same reason, it is acceptable to document the exception in the class's documentation comment rather than documenting it individually for each method. (e.g. All methods in this class throw a NullPointerException if a null object reference is passed in any parameter," or words to that effect.)
Summary
Document every exception that can be thrown by each method that you write. This is true for unchecked as well as checked exceptions, and for abstract as well as concrete methods. Provide individual throws clauses for each checked exception and do not provide throws clauses for unchecked exceptions. If you fail to document the exceptions that your methods can throw, it will be difficult or impossible for others to make effective use of your classes and interfaces.
相关文章推荐
- global.asax Application_Error method does not catch exceptions thrown by ASMX service?
- The following exceptions are thrown by certain C# operations.
- document.all还是document.getElementsByName?
- Database.Search 和 View.GetAllDocumentByKey
- document.all与getElementById、getElementsByName、getElementsByTagName用法区别-getElementById
- document.all还是document.getElementsByName?
- document.all还是document.getElementsByName?
- document.all与getElementById、getElementsByName、getElementsByTagName用法区别-document.all第1/2页
- getalldocumentbykey得到文档顺序问题
- document.all还是document.getElementsByName?
- **********method.Invoke Exception has been thrown by the target
- document.all还是document.getElementsByName?
- Document Filtering(naive bayes method) used by python
- document.all还是document.getElementsByName?
- document_all还是document_getElementsByName
- document.all与getElementById、getElementsByName、getElementsByTagName用法区别-getElementById
- Document getElementsByName() Method
- getElementByID和getElementsByName和getElementsByTagName和document.all的区别
- document,document.all,getElementById,getElementsByName,getElementsByTagName
- document,document.all,getElementById,getElementsByName,getElementsByTagName