英文原文：10 Best Practices for Code Commenting & Formatting代码注释及格式化关乎代码的可读性，而代码可读性对于代码可维护性又是至关重要的，因此一些编程的小细节有助于提高代码可维护性。本文列举了一些代码注释及格式化的优秀示例。
一、注释
注释是代码的一部分，其重要性显而易见。缺少注释的代码可以说是没有用的，虽然有人建议使用自文档化代码，不过我们认为自文档化+代码文档是最好的。
1. 只在必要时使用注释
也就是说不需要对每一行都使用注释
Java 代码
int count = 0; // 将 count 的初始值赋为0(?!?)
但缺少注释会增加维护难度，所以变量、方法的命名应该易于理解
Java 代码
int s = sqrt (v1) + v2 / v3 + fread (s). getChar (0) //(?!?)
List<int> getVal (int val, int len, String op) //(?!?)
2. 错误的注释还不如没有注释，应尽量避免。
3. 为重要的且没有自文档化的变量写注释。
4. 为公开的方法写注释（例如 JavaDoc declaration），当然，这些注释应该是真的有必要添加的。
5. 类似“了解”、“待办”的注释也许对当天来说很重要，但之后应该删除。
二、格式化
有很多开发工具（如 maven checkstyle）都提供代码格式化的功能，且格式化操作可在代码保存时自动进行，但这些格式不一定符合公司的格式规则，因此在使用之前要对其进行设置。
1. 使用一致的括号格式。括号一般都加在当前行的尾部或新一行的首部，选择一种添加方式，并在所有代码行中保持相同的格式。
2. 使用一致的空行。空行用于分隔代码和语义组，提高代码可读性。例如使用 3 行空行来表示方法的结束，没有空行或每行代码间都加空行却不利于代码美观。
3. 留意首行缩进。正确的缩进对于语义块来说就像括号和空行一样重要。
4. 限制每行的字符数，提高可读性。大多数程序员认可的限制数为 80 个左右。
5. 使用一致的空格，通常以下的这些情况要使用空格：
//运算符和变量之间
a += b , c = 0; (a == b)
//语句关键字和括号之间
if (value) {， public class A {
//循环的“；”号后
for (int i = 0; i < length; i++)
//类型和变量之间
(int) value , (String) value
最新评论