八、注释约定 · 凡普金科开发规范

## 八、注释约定 Java里的注释即是JavaDoc，可以通过内部查看源码的方式，或被生成HTML做为API帮助文档使用。 ### 典型的类和方法注释模板 >注：这个模板来自Spring源码，经过删减和修改，包含大部分注释规则， > 此模板生成后的JavaDoc请移步查看效果：http://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/beans/factory/BeanFactory.html <code> /** * The root interface for accessing a Spring bean container. * This is the basic client view of a bean container; * further interfaces such as {@link ListableBeanFactory} and * {@link org.springframework.beans.factory.config.ConfigurableBeanFactory} * are available for specific purposes. * * Normally a BeanFactory will load bean definitions stored in a configuration * source (such as an XML document), and use the {@code org.springframework.beans} * package to configure the beans. However, an implementation could simply return * Java objects it creates as necessary directly in Java code. There are no * constraints on how the definitions could be stored: LDAP, RDBMS, XML, * properties file, etc. Implementations are encouraged to support references * amongst beans (Dependency Injection). * * In contrast to the methods in {@link ListableBeanFactory}, all of the * operations in this interface will also check parent factories if this is a * {@link HierarchicalBeanFactory}. If a bean is not found in this factory instance, * the immediate parent factory will be asked. Beans in this factory instance * are supposed to override beans of the same name in any parent factory. * * Bean factory implementations should support the standard bean lifecycle interfaces * as far as possible. The full set of initialization methods and their standard order is: * 1. BeanNameAware's {@code setBeanName} * 2. BeanClassLoaderAware's {@code setBeanClassLoader} * 3. BeanFactoryAware's {@code setBeanFactory} * * On shutdown of a bean factory, the following lifecycle methods apply: * 1. DisposableBean's {@code destroy} * 2. a custom destroy-method definition * * @author Rod Johnson * @author Juergen Hoeller * @author Chris Beams * @since 13 April 2001 * @see BeanNameAware#setBeanName */ public interface BeanFactory { /** * Return the bean instance that uniquely matches the given object type, if any. * @param requiredType type the bean must match; can be an interface or superclass. * {@code null} is disallowed. * This method goes into {@link ListableBeanFactory} by-type lookup territory * but may also be translated into a conventional by-name lookup based on the name * of the given type. For more extensive retrieval operations across sets of beans, * use {@link ListableBeanFactory} and/or {@link BeanFactoryUtils}. * @return an instance of the single bean matching the required type * @throws NoSuchBeanDefinitionException if no bean of the given type was found * @throws NoUniqueBeanDefinitionException if more than one bean of the given type was found * @throws BeansException if the bean could not be created * @since 3.0 * @see ListableBeanFactory */ <T> T getBean(Class<T> requiredType) throws BeansException; } </code> #### 注释模板说明： 1. 方法上的描述和参数说明之间不需要空行； 1. 如果方法或者类的描述需要多个段落，新的段落应该以``开头； 1. 方法参数的描述说明换行后不需要缩进； 1. 每一个版本变化必须添加 `@since` 标签； 1. 类级别的标签顺序 `@author`, `@since` and `@see`； 1. 类和方法描述段落之间用空行分隔； 1. 如果要显示源代码应该添加 `{@code}` 标签； 1. 如果描述里有代码引用 `@link` 标签，应该使用类的全路径； ### 常规注释约定 1. 【强制】类、类属性、类方法的注释必须使用 Javadoc 规范，使用 `/**内容*/` 格式，不得使用 `//xxx` 方式。 说明：在 IDE 编辑窗口中，Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出相应注释；在 IDE 中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。 2. 【强制】所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。 说明：对子类的实现要求，或者调用注意事项，请一并说明。 3. 【强制】所有的类都必须添加创建者信息。 4. 【强制】方法内部单行注释，在被注释语句上方另起一行，使用 `//` 注释。方法内部多行注释使用 `/* */` 注释，注意与代码对齐。 5. 【强制】所有的枚举类型字段必须要有注释，说明每个数据项的用途。 6. 【强制】与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。 反例：“TCP 连接超时”解释成“传输控制协议连接超时”，理解反而费脑筋。 7. 【推荐】代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。 说明：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后，就失去了导航的意义。 8. 【参考】注释掉的代码尽量要配合说明，而不是简单的注释掉。说明：代码被注释掉有两种可能性：**1**）后续会恢复此段代码逻辑。**2**）永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码）。 9. 【参考】对于注释的要求：第一、能够准确反应设计思想和代码逻辑；第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。 10. 【参考】好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。 反例： ` // put elephant into fridge put(elephant, fridge); ` 方法名 put，加上两个有意义的变量名 elephant 和 fridge，已经说明了这是在干什么，语义清晰的代码不需要额外的注释。 11. 【参考】特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。 1）待办事宜（TODO）:（标记人，标记时间，[预计处理时间]）表示需要实现，但目前还未实现的功能。这实际上是一个 Javadoc 的标签，目前的 Javadoc 还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个 Javadoc 标签）。 2）错误，不能工作（FIXME）:（标记人，标记时间，[预计处理时间]）在注释中用 FIXME 标记某代码是错误的，而且不能工作，需要及时纠正的情况。 > >相关参考资料： >1. Spring编码规范： https://github.com/spring-projects/spring-framework/wiki/Spring-Framework-Code-Style >2. Google编码规范： https://google.github.io/styleguide/javaguide.html >3. 阿里巴巴开发编码规范： https://102.alibaba.com/newsInfo.htm?newsId=6