10 个代码注释及格式化的最佳实践

代码注释及格式化关乎代码的可读性，而代码可读性对于代码可维护性又是至关重要的，因此一些编程的小细节有助于提高代码可维护性。本文列举了一些代码注释及格式化的优秀示例。

一、注释

注释是代码的一部分，其重要性显而易见。缺少注释的代码可以说是没有用的，虽然有人建议使用自文档化代码，不过我们认为自文档化+代码文档是最好的。

1. 只在必要时使用注释

也就是说不需要对每一行都使用注释

Java代码

1. int count = 0; // 将count的初始值赋为0(?!?)

但缺少注释会增加维护难度，所以变量、方法的命名应该易于理解

Java代码

1. int s = sqrt(v1) + v2 / v3 + fread(s). getChar(0)  //(?!?)
2. List<int> getVal(int val, int len, String op) //(?!?)

2. 错误的注释还不如没有注释，应尽量避免。

3. 为重要的且没有自文档化的变量写注释。

4. 为公开的方法写注释（例如JavaDoc declaration），当然，这些注释应该是真的有必要添加的。

5. 类似“了解”、“待办”的注释也许对当天来说很重要，但之后应该删除。

二、格式化

有很多开发工具（如maven checkstyle）都提供代码格式化的功能，且格式化操作可在代码保存时自动进行，但这些格式不一定符合公司的格式规则，因此在使用之前要对其进行设置。

1. 使用一致的括号格式。括号一般都加在当前行的尾部或新一行的首部，选择一种添加方式，并在所有代码行中保持相同的格式。

2. 使用一致的空行。空行用于分隔代码和语义组，提高代码可读性。例如使用3行空行来表示方法的结束，没有空行或每行代码间都加空行却不利于代码美观。

3. 留意首行缩进。正确的缩进对于语义块来说就像括号和空行一样重要。

4. 限制每行的字符数，提高可读性。大多数程序员认可的限制数为80个左右。

5. 使用一致的空格，通常以下的这些情况要使用空格：

Java代码

1. //运算符和变量之间
2. a += b , c = 0; (a == b)
3. //语句关键字和括号之间
4. if (value) {, public class A {
5. //循环的“；”号后
6. for (int i = 0; i < length; i++)
7. //类型和变量之间
8. (int) value , (String) value