代码注释：像说明书一样清晰-新东方前途出国

代码注释：像说明书一样清晰

注释这个词我们都不陌生。图书或者论文中，如果引用别人的资料，或者想补充说明，编者都会加注释。但编码中的注释和书里的注释不太一样，编码中的注释更像一份说明书。比如接口部分的注释就会明确一个接口怎么使用，不可以用在哪里。

 

新人在写注释时，经常会犯一个错误—只说是什么，不说怎么用。比如对函数做注释，只对函数本身做了释义，而没有把重点放在“这个函数该怎么用”上。我之前见过一个最不好的例子是一个数学函数，注释里写的是，该函数做的事情跟另一套软件里同模块下函数做的事情是一样的。这样的注释就太随便了，根本没有考虑到别人看了注释后该怎么用。  

其实我觉得好的注释是，别人带着问题去看你这段代码和注释，看完以后问题就解决了。

 

比如C++注释规范中关于类注释的规范就描述得很清楚：可以为读者提供足够的信息，让读者知道什么时候、怎么样使用这个类，以及正确使用这个类的注意事项，如图2-4的例子：  

 

图2-4  

还有一些实现部分的注释，比如功能注释，一般要求写代码的人对每个函数声明都加上注释，描述这些函数的功能以及如何使用它，如图2-5的例子：

 

 

为什么一直在强调注释的重要性？因为当我想构造一个新的程序，觉得可能需要调用之前代码里的某个模块、某个函数的时候，脑海中会有一个大致的使用过程。当我去调用这个模块或者函数时，好的注释直接摆了个例子告诉我，你这样写就好了，我得多省事呀。就像一份说明书，你去看的时候，脑海里有一个目标，然后它会非常清晰地一步一步告诉你，这样做就可以了。这就是注释应该起到的作用。

 

点击咨询~

【免责声明】  

1、个别文章内容来源于网络善意转载，版权归原作者所有，如侵权，请联系删除；

2、所有图片来源于网络，版权归原作者所有。如有侵权问题请告知，我们会立即处理。