《事业-最佳实践-编码》系列

价值

• 提高代码的可读性和可维护性的

原则

• 用户思维

• 准确，错误的注释比没有注释更糟糕

• 必要，多余的注释浪费阅读者的时间

• 清晰，混乱的注释会把代码搞得更乱

范围

• 类注释

• 方法注释

• 属性注释

• 代码片段注释

规范

• 遵循注释原则：用户思维、准确、必要、清晰

• 重要信息注释：不要复述功能，要解释背后意图

• 注释格式：

• 类、类属性、类方法的注释必须使用 Javadoc 规范，使用/**内容*/格式，不得使用// xxx 方式

• 方法内部单行注释，在被注释语句上方另起一行，使用//注释。

• 方法内部多行注释使用/* */注释，注意与代码对齐。

• 保持注释更新：

• 当代码发生变更时，确保相应的注释也进行了更新，保持注释与代码的一致性。

• 无用代码及时清理，而不是注释掉且没有任何说明