C语言注释符号

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

C 语言的注释可以出现在C 语言代码的任何地方。这句话对不对?这是我当学生时我老师问的一个问题。我当时回答是不对。好,那我们就看看下面的例子:
A)
int/*...*/i;

B)
char* s="abcdefgh //hijklmn";

C)
//Is it a \
valid comment?

D)
in/*…*/t i;

我们知道C 语言里可以有两种注释方式:/* */ 和//。那上面3 条注释对不对呢?建议你亲自在编译器中测试一下。上述前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. 对于函数的入口出口数据给出注释。

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