《数据结构与抽象：Java语言描述（原书第4版）》一P.2.1　注释

P.2.1　注释

现在来看看为类的方法而写的注释。虽然各组织有自己的注释风格，但Java开发者有特定的应该遵从的注释风格。如果程序中含有这种风格的注释，则可以执行一个称为javadoc的实用程序，从而得到描述类的文档。这个文档告诉未来使用这些类的人们必须了解的东西，但忽略了所有实现细节，包括所有的方法定义体。
程序javadoc提取类头、所有公有方法的头，及以特定形式写的注释。每个这样的注释必须出现在公有类定义或公有方法头的前面，且必须以/*开头，以/结尾。注释中以符号@开头的特定标签（tag）标识方法的不同方面。例如，使用@param标识参数，用@return标识返回值，而用@throws标识方法抛出的异常。本序言中，在注释中会看到几个这样的标签示例。附录A详述了如何书写javadoc注释。
现在不再进一步讨论javadoc注释的规则，而是要讨论说明一个方法的重要方面。首先，你需要写一个简洁的语句来阐述方法的目的或任务。这个语句以动词开头，能让你避免冗长的文字，而那些文字真的是不需要的。
在思考方法的目的时，应该考虑它的输入参数。如果有，要描述它们。还需要描述方法的结果。是让它返回一个值、让它做些动作，还是让它改变参数的状态？在写这些描述时，应该时刻牢记以下理念。