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,并以超链接形式标明文章原始出处,否则将 ...
随机推荐
- C++ 封装互斥对象
多线程程序中为了防止线程并发造成的竞态,需要经常使用到Mutex进行数据保护.posix提供了phtread_mutex_t进行互斥保护数据.Mutex的使用需要初始化和释放对应(phtread_mu ...
- CMD魔法堂:支持显示UTF8编码的中文
一.前言 在Unbuntu中用sqlite3-command-line操作sqlite3还好好的,到了windows下查询表内容时发现中文全部乱码了!马上想到sqlite3内部使用utf-8对字符进行 ...
- 注意力机制(Attention Mechanism)在自然语言处理中的应用
注意力机制(Attention Mechanism)在自然语言处理中的应用 近年来,深度学习的研究越来越深入,在各个领域也都获得了不少突破性的进展.基于注意力(attention)机制的神经网络成为了 ...
- Scrum 项目5.0--软件工程
1.燃尽图: 2.每日立会更新任务板上任务完成情况.燃尽图的实际线,分析项目进度是否在正轨. 每天的例会结束后的都为任务板拍照并发布到博客上 团队贡献分: 蔡舜 : 21 卢晓洵 : 1 ...
- MVC知识点02
MVC基础知识详情 1:在MVC中如果要从前台页面(.aspx)获取参数,只需要将其两个页面的参数设置成一样的,这样子MVC中的机制就会自动的将参数的值传到方法中. 2:在MVC中的方法要是两个都是相 ...
- asp.net Get和Post传参和接收参数
asp.netGet和Post传参和接收参数 Get请求: 对于传参:test.aspx?name=%e5%bc%a0%e4%b8%89 接收参数的方法: Request.QueryString[&q ...
- U-boot的环境变量值得注意的有两个: bootcmd 和bootargs
本文转载至:http://www.cnblogs.com/cornflower/archive/2010/03/27/1698279.html U-boot的环境变量值得注意的有两个: bootcmd ...
- AC自动机(1)
Description Ignatius最近遇到一个难题,老师交给他很多单词(只有小写字母组成,不会有重复的单词出现),现在老师要他统计出以某个字符串为前缀的单词数量(单词本身也是自己的前缀). ...
- Dev-Cpp配置OpenGL图形库(成功版本:Dev-Cpp 5.7.1 MinGW 4.8.1)
★配置前须知:Dev-Cpp自带OpenGL的使用和OpenGL简介 (附Dev-Cpp下载地址:http://sourceforge.net/projects/orwelldevcpp/?sourc ...
- MyEclipse+Mysql (二)
上一节介绍了如何在Myeclipse中连接mysql 这一节介绍如何在java程序中访问mysql数据库中的数据b并进行简单的操作 创建一个javaProject,并输入如下java代码: packa ...