2.2 建议

建议1 避免在一行代码或表达式的中间插入注释。

说明：除非必要，不应在代码或表达式中间插入注释，否则容易使代码可理解性变差。

建议2 在代码的功能、意图层次上进行注释，提供有用、额外的信息。

说明：注释的目的是解释代码的意图、功能和采用的方法，提供代码以外的信息，帮助读者理解代码，防止没必要的重复注释信息。

示例：如下注释意义不大。

// 如果receiveFlag为真
if (receiveFlag) {
    ...
}

而如下的注释则给出了额外有用的信息。

// 如果从连接收到消息
if (receiveFlag) {
    ...
}

建议3 对关键变量的定义和分支语句（条件分支、循环语句等）必须编写注释。

说明：这些语句往往是程序实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有事甚至优于看设计文档。

建议4 注释应考虑程序易读和外观排版的因素，使用的语言若是中、英兼有的，建议多使用中文，除非能用非常流利准确的英文表达。中文注释中需使用中文标点。方法和类描述的第一句话尽量使用简洁明了的话概括一下功能，然后加以句号。接下来的部分可以详细描述。

说明：注释语言不统一，影响程序易读性和外观排版，出于对维护人员的考虑，建议使用中文。JavaDoc工具会收集第一句话作为简介。

建议5 方法内的单行注释（跟踪注释）使用 // 。

说明：调试程序的时候可以方便的使用" /*...*/ "注释掉一长段程序。

建议6 一些复杂的代码需要说明。

示例：这里主要是对闰年算法的说明。

// 1. 如果能被4整除，是闰年；
// 2. 如果能被100整除，不是闰年；
// 3. 如果能被400整除，是闰年；