还有何时需要注释?
2009-06-05 18:56
281 查看
在上篇文章中,我强调了注释的非必要性。今天重新反思了一下我设计和实现的过程,发现这篇文章还有一些需要补充的,才算完整。
在此之前,先说明一下在这两篇文章中,那些“真正”属于注释范畴的东西:既提供给作者和修改者看的,和代码放在一起的文本。
对于提供给使用者看的文本,比如上篇文章中提到的接口描述,无论是否采用了注释的形式,一概算作文档,不在讨论范畴之内。
1. 一句或一段代码抽象过了头,也许需要跟业务相关的描述建立一个直观的对应。
2. 因为安排的不够妥帖或者很难妥帖,一段逻辑中蹦出一句为不相关逻辑服务的代码。
实际上除了这些,还有两种场景让我去写注释:
3. 脑袋说的那种对接下来要实现的东西的描述,在我的代码中体现为“//TODO:”。
4. 另外一种情况,我自己认为这里有问题,但是暂时选择了不去修改它,体现为“//CAUTION:”。
这两种情况和上面两种是不同的。
这样的注释,会随着项目的进行和重构,一点一点的消失掉。最终我会Find in Files,确认这两个标记已经不在了。
无论如何,这也是注释,而且它们对我产生了帮助。还有什么是需要注释、或者说注释可以帮助我们的?
有一些代码留下这样的注释:“以下算法实现了论文xxxxxx,时间复杂度是m,另有论文yyyyy,时间复杂度为n”。
这就又多了一种情况:
5. 这种一句话交代背景、指向文档的注释也总是有作用的,它们是一种建立联系的索引。
这种注释和第一种有相似性,但又有所不同。
我相信还有其它类似的经验,希望掌握它们的兄弟为大家提个醒,让这个讨论变成建设性的,而不仅仅是一种辩论。
我个人仅仅是认为,让不写注释的兄弟去照顾写注释的,不像很多人想象的那样理所应当,这个上篇文章基本阐述清楚了我的想法。
对于这个问题,下面再补充一个我个人的经历,有兴趣的可以看看,没兴趣的可以跳过了。
大家可以先看一下这段代码,这是一个简单的使用javascript解析javascript语法子集的例子。当初我将这段代码翻译成python的,一共花费了1天左右的功夫。
在核心函数expression的注释上,我花了3个小时去写和改。按照我当时的认识,我会认为这是因为这段代码的复杂度要求我阐述其逻辑,我甚至举了一个精心的例子来描述其执行流程。
实际上昨天看这些代码(原装的和我翻译的)时,我真正的感受是,这个东西设计的真不咋地。假设当初我看到的是更好的设计和实现,我根本就不会花费那么时间和精力。
如果这段(原装的)代码是我身边的人写的,那么我会要求他去重构,而不是补上注释。事实上正是因为结构设计的不够优良,实现的也不清晰,才导致自己和别人产生理解上的种种障碍。
如果说当初我在翻译版本中留下的注释有什么作用,就是提醒我“这段相对其它内容比较复杂,需要仔细一点”。考虑我对自己原先写下的注释(肯定不是错误的)的反应,我不太相信它们能对其他人发挥什么良好作用。
这段代码的核心是递归下降与算符优先的结合,有人可能注意到了,其作者Douglas Crockford有比注释更详细的文本解释其来龙去脉。更多的内容还出现在《代码之美》之中,我第一次翻译的时候这个中文版就在我手边。
我要说的是什么呢?我不能说这些文本在当时对我一点帮助没有,但是我个人认为,即使如此详尽的文本,对阅读代码而言,也抵不上清晰可读的结构。
况且,对于一个有限的时间,我们能写出十好几页16开的注释吗?
在此之前,先说明一下在这两篇文章中,那些“真正”属于注释范畴的东西:既提供给作者和修改者看的,和代码放在一起的文本。
对于提供给使用者看的文本,比如上篇文章中提到的接口描述,无论是否采用了注释的形式,一概算作文档,不在讨论范畴之内。
对注释有帮助的情况的个人经验补充
引用一下上一篇文章说的两种情况:1. 一句或一段代码抽象过了头,也许需要跟业务相关的描述建立一个直观的对应。
2. 因为安排的不够妥帖或者很难妥帖,一段逻辑中蹦出一句为不相关逻辑服务的代码。
实际上除了这些,还有两种场景让我去写注释:
3. 脑袋说的那种对接下来要实现的东西的描述,在我的代码中体现为“//TODO:”。
4. 另外一种情况,我自己认为这里有问题,但是暂时选择了不去修改它,体现为“//CAUTION:”。
这两种情况和上面两种是不同的。
这样的注释,会随着项目的进行和重构,一点一点的消失掉。最终我会Find in Files,确认这两个标记已经不在了。
无论如何,这也是注释,而且它们对我产生了帮助。还有什么是需要注释、或者说注释可以帮助我们的?
有一些代码留下这样的注释:“以下算法实现了论文xxxxxx,时间复杂度是m,另有论文yyyyy,时间复杂度为n”。
这就又多了一种情况:
5. 这种一句话交代背景、指向文档的注释也总是有作用的,它们是一种建立联系的索引。
这种注释和第一种有相似性,但又有所不同。
我相信还有其它类似的经验,希望掌握它们的兄弟为大家提个醒,让这个讨论变成建设性的,而不仅仅是一种辩论。
对上篇文章讨论的一些补充
那种描述逻辑的注释真的有用吗?按照脑袋的体验是有用的,但是我觉得这种经验确实不是放之四海皆准的;同样,注释无用论也不见得适合每一个人。我个人仅仅是认为,让不写注释的兄弟去照顾写注释的,不像很多人想象的那样理所应当,这个上篇文章基本阐述清楚了我的想法。
对于这个问题,下面再补充一个我个人的经历,有兴趣的可以看看,没兴趣的可以跳过了。
大家可以先看一下这段代码,这是一个简单的使用javascript解析javascript语法子集的例子。当初我将这段代码翻译成python的,一共花费了1天左右的功夫。
在核心函数expression的注释上,我花了3个小时去写和改。按照我当时的认识,我会认为这是因为这段代码的复杂度要求我阐述其逻辑,我甚至举了一个精心的例子来描述其执行流程。
实际上昨天看这些代码(原装的和我翻译的)时,我真正的感受是,这个东西设计的真不咋地。假设当初我看到的是更好的设计和实现,我根本就不会花费那么时间和精力。
如果这段(原装的)代码是我身边的人写的,那么我会要求他去重构,而不是补上注释。事实上正是因为结构设计的不够优良,实现的也不清晰,才导致自己和别人产生理解上的种种障碍。
如果说当初我在翻译版本中留下的注释有什么作用,就是提醒我“这段相对其它内容比较复杂,需要仔细一点”。考虑我对自己原先写下的注释(肯定不是错误的)的反应,我不太相信它们能对其他人发挥什么良好作用。
这段代码的核心是递归下降与算符优先的结合,有人可能注意到了,其作者Douglas Crockford有比注释更详细的文本解释其来龙去脉。更多的内容还出现在《代码之美》之中,我第一次翻译的时候这个中文版就在我手边。
我要说的是什么呢?我不能说这些文本在当时对我一点帮助没有,但是我个人认为,即使如此详尽的文本,对阅读代码而言,也抵不上清晰可读的结构。
况且,对于一个有限的时间,我们能写出十好几页16开的注释吗?
相关文章推荐
- PowerDesigner16.5快速入门显示,注释comment配置方法,以及创建sql文件过程中需要注意的一些问题
- PowerDesigner16.5快速入门显示,注释comment配置方法,以及创建sql文件过程中需要注意的一些问题
- EF需要注意的virtual,懒加载,还有1对n更新
- 网易出的区块链 星球 邀请码 ,还有 2 次,共享在此,需要的拿走。
- 看看你与企业需要的人才还有哪些差距?
- 问题2:你使用过几种方式在网上发布信息?都有什么?你认为还有那些工具需要学习的?每问必答,长短不限
- 看不懂,能不能帮我写注释?还有bool什么意思?
- 什么是预处理,何时需要预处理?
- 何时需要非规范化
- Eclipse + Spring + maven Building a RESTful Web Service ---需要添加注释
- el表达式在js中有时需要加引号才可以用,何时需要加引号,何时不需要加引号
- [导入]写组件时需要的注释与属性书写方法
- 单例中的堆内存是否需要释放? 何时释放?
- 《C++精英内参之程序员高效指南》-11常用的读代码方法除了写注释的,还有其他方法
- 何时需要使用getMeasuredHeight()\getMeasuredWidth()?
- SpringMVC中的注释@Param引用不到,需要引入什么包呢?
- 对于equal和hashcode的理解,何时需要重写
- 查新功能的一些bug点还有开发需要注意的事项
- 线程同步:何时互斥锁不够,还需要条件变量?
- 何时应将引用形参定义为 const 对象?如果在需要 const 引用时,将形参定 义为普通引用,则会出现什么问题?