代码审美

  • 使用一致布局,风格统一
  • 让相似的代码看上去相似
  • 把相关的代码行分组,形成代码块

选有意义的顺序

如下面代码:

1
2
3
4
5
details = request.get("details");
location = request.get("location");
phone = request.get("phone");
email = request.get("email");
url = request.get("url");

上面的情况下,不要随机的排序,把他们按照有意义的顺序排列会更好。可以使用如下的方法:

  • 变量的顺序与 html 表单的顺序相同
  • 从最重要到最不重要
  • 按字母顺序

把代码分成段落

一大段代码堆在一起不便于阅读,所以将相同类型的代码放在一块,与其他的代码进行分开,更加便于阅读和查找。

注释

注释的目的是尽量帮助读者了解的和作者一样多。

不要为那些从代码本身就能快速推断的事实写注释。

不要给不好的名字加注释,应该把名字修改好。

需要加的注释是记录了作者想法的东西。

给常量加上注释:

1
2
3
4
/**
* The default initial capacity - MUST be a power of two.
*/
static final int DEFAULT_INITIAL_CAPACITY = 1 << 4; // aka 16

这个是 JDK 当中 HashMap 当中的常量的注释,说明了这个常量的值应该是2的 N 次幂,表达了更多的信息。当然有写常量的不需要加上注释的,因为名字已经很清晰了

在一些不常用的细节的时候应该给予注释说明。例如:

1
2
3
4
5
6
7
struct Recorder{
vector<float> data;
...
void Clear() {
vector<float>.swap(data);
}
}

上面的例子当中方法名字上 Clear 但是内部实现确实 swap 方法,这个就上 c++ 当中的细节,只有这样才能把内存真正归还给内存分配器。

注释也应该描述潜在的陷阱。如果一个函数调用时间会很长,就需要注释来说明下。

在一个重要的类上也需要写上文件级别的注释,简单说明下这个类的作用。

在一段复杂的代码上加上总结性的注释会更加便于理解,如果不需要看代码的细节就知道这段代码的作用,同时也可以根据这段注释来深入了解这段代码的实现。

写出言简意赅的注释

注释应该有很高的信息/空间率。

注释应该精确的描述函数的行为,这个可以参考下 apache common lang 里面对字符串的处理的工具类 StringUtils 类里面方法的注释。

对于输入/输出的函数也可以在注释的时候举一个例子来说明这个函数的作用。

当然还有很总要的是,当以前写的代码有变动的时候也一个及时更新这个函数的注释。否则当你再次看代码的时候就会发现代码和注释说的不是一个事情,到时候就会非常的混乱。

—EOF—