Effective Java 44 Write doc comments for all exposed API elements
Principle
- You must precede every exported class, interface, constructor, method, and field declaration with a doc comment.
- If a class is serializable, you should also document its serialized form (Item 75).
- To write maintainable code, you should also write doc comments for most unexported classes, interfaces, constructors, methods, and fields.
- What comment to doc
The doc comment for a method should describe succinctly the contract between the method and its client. With the exception of methods in classes designed for inheritance (Item 17), the contract should say what the method does rather than how it does its job.
- Happypath
The doc comment should enumerate all of the method's preconditions, which are the things that have to be true in order for a client to invoke it, and its postconditions , which are the things that will be true after the invocation has completed successfully.
- Exception path
Typically, preconditions are described implicitly by the @throws tags for unchecked exceptions; each unchecked exception corresponds to a precondition violation. Also, preconditions can be specified along with the affected parameters in their @param tags.
- Side effects
An observable change in the state of the system that is not obviously required in order to achieve the postcondition. For example, if a method starts a background thread, the documentation should make note of it.
- Thread safety
Describe the thread safety of a class or method, as discussed in Item 70.
- Tag description
- @param - a noun phrase describing the value represented by parameter.
- @return - a noun phrase describing the value represented by return value.
- @throws - consist of the word "if", followed by a clause describing the conditions under which the exception is thrown. Occasionally, arithmetic expressions are used in place of noun phrases.
- {@code} - it causes the code fragment to be rendered in code font, and it suppresses processing of HTML markup and nested Javadoc tags in the code fragment.
precede the multiline code example with the characters <pre>{@code and follow it with the characters }</pre>.
/**
* Returns the element at the specified position in this list.
*
* <p>This method is <i>not</i> guaranteed to run in constant
* time. In some implementations it may run in time proportional
* to the element position.
*
* @param index index of element to return; must be
* non-negative and less than the size of this list
* @return the element at the specified position in this list
* @throws IndexOutOfBoundsException if the index is out of range
* ({@code index < 0 || index >= this.size()})
*/
E get(int index);
- Use the word "this" always to refers to the object on which the method is invoked when it is used in the doc comment for an instance method.
- {@literal} - suppress processing of HTML markup and nested Javadoc tags. Unlike {@Code} tag it doesn't render the test in code font.
* The triangle inequality is {@literal |x + y| < |x| + |y|}.
produces the documentation: "The triangle inequality is |x + y| < |x| + |y|."
- Doc comments should be readable in both the source code and in the generated documentation. If you can't achieve both, generated documentation readability trumps source code readability.
- No two members or constructors in a class or interface should have the same summary description.
- If the intended summary description contains a period , because the period can prematurely terminate the description.
/**
* A college degree, such as B.S., {@literal M.S.} or Ph.D.
* College is a fountain of knowledge where many go to drink.
*/
public class Degree { ... }
9. For methods and constructors, the summary description should be a full verb phrase (including any object) describing the action performed by the method.
• ArrayList(int initialCapacity) —Constructs an empty list with the specified initial capacity.
• Collection.size()—Returns the number of elements in this collection.
10. For classes, interfaces, and fields, the summary description should be a noun phrase describing the thing represented by an instance of the class or interface or by the field itself.
• TimerTask—A task that can be scheduled for one-time or repeated execution by a Timer.
• Math.PI—The double value that is closer than any other to pi, the ratio of the circumference of a circle to its diameter.
11. When documenting a generic type or method, be sure to document all type parameters:
/**
* An object that maps keys to values. A map cannot contain
* duplicate keys; each key can map to at most one value.
*
* (Remainder omitted)
*
* @param <K> the type of keys maintained by this map
* @param <V> the type of mapped values
*/
public interface Map<K, V> {
... // Remainder omitted
}
12. When documenting an enum type, be sure to document the constants as well as the type and any public methods.
/**
* An instrument section of a symphony orchestra.
*/
public enum OrchestraSection {
/** Woodwinds, such as flute, clarinet, and oboe. */
WOODWIND,
/** Brass instruments, such as french horn and trumpet. */
BRASS,
/** Percussion instruments, such as timpani and cymbals */
PERCUSSION,
/** Stringed instruments, such as violin and cello. */
STRING;
}
13. When documenting an annotation type, be sure to document any members as well as the type itself.
/**
* Indicates that the annotated method is a test method that
* must throw the designated exception to succeed.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
/**
* The exception that the annotated test method must throw
* in order to pass. (The test is permitted to throw any
* subtype of the type described by this class object.)
*/
Class<? extends Exception> value();
}
14. If a class is serializable, you should document its serialized form, as described in Item 75.
15. Javadoc has the ability to "inherit" method comments. If an API element does not have a doc comment, Javadoc searches for the most specific applicable doc comment, giving preference to interfaces over superclasses. You can also inherit parts of doc comments from super types using the {@inheritDoc} tag.
16. For complex APIs consisting of multiple interrelated classes, it is often necessary to supplement the documentation comments with an external document describing the overall architecture of the API. If such a document exists, the relevant class or package documentation comments should include a link to it.
Summary
Documentation comments are the best, most effective way to document your API. Their use should be considered mandatory for all exported API elements. Adopt a consistent style that adheres to standard conventions. Remember that arbitrary HTML is permissible within documentation comments and that HTML meta characters must be escaped.
Effective Java 44 Write doc comments for all exposed API elements的更多相关文章
- Effective Java Index
Hi guys, I am happy to tell you that I am moving to the open source world. And Java is the 1st langu ...
- 《Effective Java》读书笔记 - 7.方法
Chapter 7 Methods Item 38: Check parameters for validity 直接举例吧: /** * ...其他的被我省略了 * @throws Arithmet ...
- Effective Java 目录
<Effective Java>目录摘抄. 我知道这看起来很糟糕.当下,自己缺少实际操作,只能暂时摘抄下目录.随着,实践的增多,慢慢填充更多的示例. Chapter 2 Creating ...
- 【Effective Java】阅读
Java写了很多年,很惭愧,直到最近才读了这本经典之作<Effective Java>,按自己的理解总结下,有些可能还不够深刻 一.Creating and Destroying Obje ...
- How to Write Doc Comments for the Javadoc Tool
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html This document describe ...
- Effective Java 第三版——44. 优先使用标准的函数式接口
Tips <Effective Java, Third Edition>一书英文版已经出版,这本书的第二版想必很多人都读过,号称Java四大名著之一,不过第二版2009年出版,到现在已经将 ...
- 如何写Java文档注释(Java Doc Comments)
本文翻译自How to Write Doc Comments for the Javadoc Tool,但是精简了一些私以为不重要的东西 本文不讨论如何使用javadoc工具自动生成文档的方法,而是主 ...
- Effective java笔记(六),方法
38.检查参数的有效性 绝大多数方法和构造器对于传递给它们的参数值都会有限制.如,对象引用不能为null,数组索引有范围限制等.应该在文档中指明所有这些限制,并在方法的开头处检查参数,以强制施加这些限 ...
- [Effective Java]第八章 通用程序设计
声明:原创作品,转载时请注明文章来自SAP师太技术博客( 博/客/园www.cnblogs.com):www.cnblogs.com/jiangzhengjun,并以超链接形式标明文章原始出处,否则将 ...
随机推荐
- [编辑器]走上atom之路1
祝大家新年快乐 我就是来卖个萌,逃- 正文 我最开始用atom是因为它看起来比较酷,我工作中主力还是使用pycharm,毕竟atom只是一个编辑器.我一 般只是用atom来写Markdown的文件.随 ...
- 数据库收缩:NOTRUNCATE与TRUNCATEONLY
在进行数据库收缩时,我们有2个可用选项:NOTRUNCATE,TRUNCATEONLY.这篇文章我们会详细讨论下这2个选项的具体区别. NOTRUNCATE 当你对数据库收缩命令提供NOTRUNCAT ...
- eclipse中 properties文件编码问题
1. Eclipse修改设置 项目中用到了配置文件,所以在Eclipse中新建.properties文件,文件中编辑了中文,在保存时Eclipse报出以下错误: 解决这个问题的方法: 依次选择: 菜单 ...
- thread_CyclicBarrier回环栅栏
CyclicBarrier回环栅栏,字面意思是可循环使用(Cyclic)的屏障(Barrier).通过它可以实现让一组线程等待至某个状态之后再全部同时执行. 它要做的事情是,让一组线程到达一个屏障(也 ...
- KTV点歌系统
经过十多天的艰苦奋战,MyKTV点歌系统终于成型,从刚开始接到项目的茫然,到完成项目时的喜悦,整个过程的艰辛和付出只有自己知道.虽然这个项目还有许多需要完善的地方,譬如添加歌词信息,实现窗体的美化等, ...
- 【jQuery基础学习】04 jQuery中的表格操作及cookie插件的使用
这章本来准备写成jQuery的表单操作和表格操作的. 然而昨天吧jQuery的表单操作看完,发现全部在炒之前章节的剩饭,所以就没写出来. 那么今天就来看看表格吧. 因为平常做的都是公司的内部管理系统, ...
- 测试驱动开发(TDD)的思考
极限编程 敏捷开发是一种思想,极限编程也是一种思想,它与敏捷开发某些目标是一致的.只是实现方式不同.测试驱动开发是极限编程的一部分. 1.极限编程这个思路的来源 Kent Beck先生最早在其极限编程 ...
- log4j.xml 配置参数属性level使用心得
jdbc.sqlonly 只显示执行的sql语句.info级才可以显示,debug增加显示java源代码位置. jdbc.sqltiming 显示执行的sql语句以及语句执行时间, ...
- Math对象常用方法汇总
前几天翻阅<JavaScript权威指南>,看到了Math对象,于是汇总了一下. Math对象不同于其他的对象,它可以说是一个公共数学类,里面有很多数学方法,用于各种数学运算,但是Math ...
- KindEditor编辑器在ASP.NET中的使用
KindEditor编辑器在ASP.NET中的使用 最近做的项目中都有用到富文本编辑器,一直在寻找最后用的富文本编辑器,之前用过CKEditor,也用过UEditor,这次打算用 一下KindEdit ...