标注函数，而不是标注代码块

 

 

我听过很多关于标注的看法了。

比如jf说，“我发现我们都不太写标注，我们新来的，看起来比较困难”。那么，让你看不懂的真的是因为没有标注吗？在我的经验中，大部分原因在于：首先是因为代码本身不够清晰，导致需要标注，因此，真正的症结在于代码，而不在于标注。尤其是应用程序，大部分代码距离用户界面都不远，因此，只要用户界面走得通流程，通常不必但是在代码中迷路，因此代码都应该是比较容易理解的。这里引入了一个有趣的概念，叫做函数之间的距离。缩小代码的距离是高效编写代码的关键。但是常常是被人忽视的。以后在慢慢参详。

我刚刚看到一篇文章，惹恼程序员的10件事情，其中的6，5和标注有关。第5条是程序员发现代码没有标注，第6条是让程序员写标注，这两条都会让程序员恼怒。是不是非常有趣？

当然，有标注比没有标注强。这也是不可否认的。

还有人说，标注应该是比较规矩的。比如第一步，第二步，第三步… ,类似这样的代码

Foo()

{

// step1 :do something

…

…

...

// step2 :do otherthing

…

…

...

 

// step3 :do anotherthing

…

…

…

}

对此我也不以为然。这样的编码可以是过程中的一部分，而不应该是结果——遇到这样的情况，一定记得加上一个重构环节，通过“函数抽取”把他分解为多个函数。标注可以继续存在，但是应该标注到函数上，而不是代码块。代码的样子应该是：

Foo()

{

Step1();

Step2();

Step3();

}

 

// step1 :do something

Step1()

{

…

…

…

}

// step2 :do otherthing

Step2()

{

…

…

…

}

 

// step3 :do anotherthing

Step3()

{

…

…

…

}

像是这样的写法，第一层函数Foo的代码内还需要标注吗？根本就不再需要标注了。

 

人们总是不容易发现自己的问题，但是总很容易发现其他人的问题。自己发起对自己的代码的问题查找和修改总是缺乏动机。因此review是有价值的。不管是代码标注问题，还是一般的代码质量问题，都可以通过review的方法来达到比较好的效果。