代码告诉你如何，注释告诉你为何

在之前一些关于代码注释的文章中，我发现，你不须要的注释才是最好的注释。不要急着批判，请容许我阐述一下。首先代码应该尽可能地简洁，尽量地作到不须要依赖注释就能够理解。只有那些真的无法更易于理解的代码，才须要咱们添加注释。

 

有一本很是经典的书叫《Structure and Interpretation of Computer Programs》（《电脑程序的结构和编译》），最初发表于1985年，在序言中就代表其观点：

引用

程序必须能便于咱们阅读，让机器执行只是附带的。

Knuth也在他1984年发表的经典论文《Literate Programming》（《文学编程》）中秉持了相似的观点：

引用

咱们应该转变传统的思惟，程序再也不是告诉计算机作什么的指令，而是向人类描述如何让计算机作事情的文字，编程像写文章同样。

文学编程关注的主要是展示精致的风格。程序员应该像做家同样，认真地选择变量名，并解释每一个变量的意思，努力写出易于人脑理解的程序。

若是你写出来的代码，既能被其余程序员理解又能成功编译，那么须要添加注释的地方确定就不会不少。关于使用注释做为辅助工具，下面就是一个颇具表明意义的例子：

这段代码取自一个已经使用多年、闭源了的系统。

引用

float _x = abs(x – deviceInfo->position.x) / scale;

int directionCode;

if (0 < _x & x != deviceInfo->position.x) {

if (0 > x – deviceInfo->position.x) {

directionCode = 0x04 /*left*/;

} else if (0 < x – deviceInfo->position.x) {

directionCode = 0x02 /*right*/;

}

}

上面的代码等同于下面的代码，可是下面的代码可读性更高。

引用

static const int DIRECTIONCODE_RIGHT = 0x02;static const int DIRECTIONCODE_LEFT = 0x04;static const int DIRECTIONCODE_NONE = 0x00;

int oldX = deviceInfo->position.x;

int directionCode = (x > oldX) ? DIRECTIONCODE_RIGHT : (x > oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;

须要注意的是，注释的越多并不意味着代码的理解性更强。固然在本案例中并无涉及到这一点。上面的注释——若是你注意到的话——使得代码更加显得凌乱不堪。有时候，注释得越精简代码的可读性才越高。特别是在你必须更换使用其余符号名的状况下。

虽然咱们能无限次地重构和精简代码以免写繁冗的注释，可是表述本身的思考过程的方式倒是有局限性的。

不管最后你呈现的代码是有多么的简洁和清楚，代码也不可能彻底自文档化。可是代码永远也不可能取缔注释的存在。正如Jef Raskin所说：

[代码]没法解释如此写程序以及选择该方法的缘由。从[代码]上咱们也看不出选择某些替代方法的理由。例如：

引用

/* A binary search turned out to be slower than the Boyer-Moore algorithm for the data sets of interest, thus we have used the more complex, but faster method even though this problem does not at first seem amenable to a string search technique. */

在A开发人员看来彻底显而易见的东西，可能在B眼里彻底就像雾里看花同样。因此咱们在写注释的时候，也要考虑到这一点：

下面这个可能你一清二楚

引用

$string = join(”,reverse(split(”,$string)));

反转字符串，可是要如何才能插入到

引用

# Reverse the string

Perl文件中呢？

的确，这一点都不难。归根究底，代码只会告诉你程序是如何工做的，可是注释则能说明工做的缘由。因此，下次你写代码的时候，不妨在这两个方面给你的同事作个榜样。

英文原文：Code Tells You How, Comments Tell You Why

 

 

另外若是你想更好的提高你的编程能力，学好C语言C++编程！弯道超车，快人一步！笔者这里或许能够帮到你~

分享（源码、项目实战视频、项目笔记，基础入门教程）

欢迎转行和学习编程的伙伴，利用更多的资料学习成长比本身琢磨更快哦！

免费学习书籍：

 

免费学习资料：