正文
受众
代码的维护者
代码的使用者、维护者
代码维护者
编写视角
代码实现视角，强调how、why，是关于代码的实现细节
业务能力视角，强调What，是代码所提供的能力
代码实现视角
格式要求
单行注释以//开头；多行注释以/*开头，并以*/结束
应遵循Javadoc编写规范：
《Javadoc规范》。基于JDK提供的Javadoc工具，可生成HTML格式的API文档
无
实践建议
1.
保持简洁，避免过度注释
2.
避免注释对代码的直译（听君一席话、如听一席话）
3.
代码应该自解释，注释只在必要时添加
4.
随着代码的变更，确保相关的注释也得到相应更新；过期甚至是错误的注释是有害的
1.
对于所有公共类和公共方法，应该始终提供详细的Javadoc
2.
Javadoc要避免暴露过多的细节，特别是一些敏感信息
3.
随着代码的变更，确保相关的Javadoc也得到相应更新；过期甚至是错误的注释是有害的
4.
借助各类IDE提自动生成Javadoc，以提高效率并确保一致性
5.
无论代码是否自注释，都必须提供详细的Javadoc
1.
严格遵循代码变量和方法的命名规范，名字需具备业务语义
2.
用有语义的方法或变量替代复杂的逻辑，使代码更容易理解；这需要控制方法复杂度和内聚性，简化代码结构
3.
如果业务发生变化，则先变更语义（如方法名）再变更实现（如方法实现逻辑）
4.
尽可能通过代码自注释来减少注释，从而减低维护成本；但不应替代Javadoc
▐ 案例解读
/** * Gets a property from the configuration. * * @param key property to retrieve * @return value as object. Will return user value if exists, * if not then default value if exists, otherwise null */ public Object getProperty(String key) { // first, try to get from the 'user value' store Object obj = this.get(key);
if (obj == null) { // if there isn't a value there, get it from the // defaults if we have them if (defaults != null) { obj = defaults.get(key); } }
return obj; }
// org.apache.commons.collections.ExtendedProperties
在Java编码中，当我们需要处理异常时，一般会对异常信息进行组织，然后将异常信息通过异常继续向上抛出（如果当前无法处理异常），同时打印异常日志。异常信息和异常日志，以不同的方式对外反馈系统发生的异常情况，帮助理解并解决系统问题。它们从产出时机看是一致的，所包含的内容也是高度一致的。在实际编码中，我们会存在“处理了异常但不打印日志”、“异常信息和异常日志输出的比较随意”等情况，这一般是未充分考虑两者在实际的维护中起到的不同作用，从而增加了系统维护的难度和成本。
▐ 概念比较
-
异常信息：
程序在运行时遇到异常时，抛出的异常所带的描述性信息；它通常包括异常的类型、描述性消息和堆栈跟踪。
-
异常日志：
程序在处理异常时，同步输出的日志信息；它通常包含异常发生的原因、异常发生时业务上下文以及其他一些关键信息。
