八、注釋約定 · 凡普金科開發規范

## 八、注釋約定 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