C语言注释符号

一、几个似非而是的注释问题

C 语言的注释可以出现在C 语言代码的任何地方。这句话对不对？这是我当学生时我老师问的一个问题。我当时回答是不对。好，那我们就看看下面的例子：

我们知道C 语言里可以有两种注释方式：/* */ 和//。那上面3 条注释对不对呢？建议你亲自在编译器中测试一下。上述前３条注释都是正确的，最后一条不正确。

A),有人认为编译器剔除掉注释后代码会被解析成inti，所以不正确。编译器的确会将注释剔除，但不是简单的剔除，而是用空格代替原来的注释。再看一个例子：
    /*这是*/#/*一条*/define/*合法的*/ID/*预处理*/replacement/*指*/list/*令*/

你可以用编译器试试。

B),我们知道双引号引起来的都是字符串常量，那双斜杠也不例外。

C),这是一条合法的注释，因为/是一个接续符。关于接续符，下面还有更多讨论。

D), 前面说过注释会被空格替换，那这条注释不正确就很好理解了。

现在你可以回答前面的问题了吧？但注意：/*…*/这种形式的注释不能嵌套，如：
    /*这是/*非法的*/*/

因为/*总是与离它最近的*/匹配。

二、y = x/*p

y = x/*p，这是表示x 除以p 指向的内存里的值，把结果赋值为y？我们可以在编译器上测试一下，编译器提示出错。

实际上，编译器把/*当作是一段注释的开始，把/*后面的内容都当作注释内容，直到出现*/为止。这个表达式其实只是表示把x 的值赋给y，/*后面的内容都当作注释。但是，由于没有找到*/，所以提示出错。

我们可以把上面的表达式修改一下：
    y = x/ *p

或者
    y = x/(*p)

这样的话，表达式的意思就是x 除以p 指向的内存里的值，把结果赋值为y 了。

也就是说只要斜杠（/）和星号（*）之间没有空格，都会被当作注释的开始。这一点一定要注意。

三、怎样才能写出出色的注释

注释写得出色非常不容易，但是写得糟糕却是人人可为之。糟糕的注释只会帮倒忙。

1、安息吧，路德维希.凡.贝多芬

在《Code Complete》这本书中，作者记录了这样一个故事：有位负责维护的程序员半夜被叫起来，去修复一个出了问题的程序。但是程序的原作者已经离职，没有办法联系上他。这个程序员从未接触过这个程序。在仔细检查所有的说明后，他只发现了一条注释，如下：
    MOV AX 723h ;R.I.P.L.V.B.

这个维护程序员通宵研究这个程序，还是对注释百思不得其解。虽然最后他还是把程序的问题成功排除了，但这个神秘的注释让他耿耿于怀。说明一点：汇编程序的注释是以分号开头。

几个月后，这名程序员在一个会议上遇到了注释的原作者。经过请教后，才明白这条注释的意思：安息吧，路德维希.凡.贝多芬（Rest in peace, Ludwig Van Neethoven）。贝多芬于1827 年逝世，而1827 的十六进制正是723。这真是让人哭笑不得！

2、windows 大师们用注释讨论天气问题

还有个例子：前些日子windows 的源代码曾经泄漏过一部分。人们在看这部分大师的经典作品时，却发现很多与代码毫无关系的注释！有的注释在讨论天气，有的在讨论明天吃什么，还有的在骂公司和老板。这些注释虽然与代码无关，但总比上面那个让贝多芬安息的注释要强些的。至少不会让你抓狂。不过这种事情只有大师们才可以做，你可千万别用注释
讨论天气。

3、出色注释的基本要求

1. 注释应当准确、易懂，防止有二义性。错误的注释不但无益反而有害。
2. 边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释要及时删除。
3. 注释是对代码的“提示”，而不是文档。程序中的注释应当简单明了，注释太多了会让人眼花缭乱。
4. 一目了然的语句不加注释。例如：i++; /* i 加1 */——多余的注释
5. 对于全局数据（全局变量、常量定义等）必须要加注释。
6. 注释采用英文，尽量避免在注释中使用缩写，特别是不常用缩写。因为不一定所有的编译器都能显示中文，别人打开你的代码，你的注释也许是一团乱码。还有，你的代码不一定是懂中文的人阅读。
7. 注释的位置应与被描述的代码相邻，可以与语句在同一行，也可以在上行，但不可放在下方。同一结构中不同域的注释要对齐。
8. 当代码比较长，特别是有多重嵌套时，应当在一些段落的结束处加注释，便于阅读。
9. 注释的缩进要与代码的缩进一致。
10. 注释代码段时应注重“为何做（why）”，而不是“怎么做（how）”。说明怎么做的注释一般停留在编程语言的层次，而不是为了说明问题。尽力阐述“怎么做”的注释一般没有告诉我们操作的意图，而指明“怎么做”的注释通常是冗余的。
11. 数值的单位一定要注释。注释应该说明某数值的单位到底是什么意思。比如：关于长度的必须说明单位是毫米，米，还是千米等；关于时间的必须说明单位是时，分，秒，还是毫秒等。
12. 对变量的范围给出注释。
13. 对一系列的数字编号给出注释，尤其在编写底层驱动程序的时候（比如管脚编号）。
14. 对于函数的入口出口数据给出注释。

关于函数的注释在函数那章有更详细的讨论。