也谈代码中注释的问题
2014-04-03 11:02
120 查看
对于代码注释,大家较为一致的看法是代码中一定要有注释,这是毫无疑问的,但是如何去写注释,却是各有各的说法,今天看到一篇博客,其观点是:注释只写why,不写what和how。当然,前提是代码已能够很容易看出 what和how了。看了这博客,我也想谈谈这方面的看法。
在注释的问题上,很久以前还跟我的一位同事吵过,那位同事在代码上密密麻麻地写满注释,他让我也要这样做,这让我很不能接受,因为我觉得我的代码一下就可以看明白的,不需要那么多的注释,除非他英语很差,需要我把它翻译成中文才能看明白,而且我的注释都是英文的注释,那位同事的注释是全中文的,他几乎为每一行语句都做了中文注释,让我感觉他象是在为他的代码做中文翻译,我始终觉得作为一名程序员,起码要过英语这一关,如果英语不行,可以想象他的代码可读性会非常差,他写的函数名、变量名会很难让人看明白,那只好在他的代码上密密麻麻地写满中文翻译了,但我觉得这样的程序员不是称职的程序员。为函数名、变量名取一个很容易让人看明白的名字,胜过写一大堆的注释,容易让人理解、容易让人记得住的函数名、变量名,用起来也让人舒心,在写代码中最为烦恼的是当要用某个函数或变量时,却不知道名字该怎么打出来,而且总让人记不住,我最恨有这样的函数名和变量名。
那到底什么样的注释才算是合理的呢?我觉得一方面要让程序员从繁琐的注释中解脱出来,让他能够更加关注程序的设计问题,另一方面还要确保代码的可读性。写代码也关系到做人的问题,有些人仅为自己考虑,觉得只要自己能够看得懂就可以了,殊不知在公司中写的代码是公司的,是很有可能要让其他人接手维护的,所以我们在写代码时也要为别人考虑,要站在别人角度来看自己写的代码,当觉得自己的某段代码或某行语句可能会让人很难理解时,则一定要写上足够的注释,我觉得这是为代码写注释的最基本的原则。
看别人的代码总觉得很累,代码是抽象的,不管注释再多,要把别人写的代码全部理解下来,总要死掉不少的脑细胞,所以万不得已时我一般不去看别人写的代码,除非那代码需要我去维护,如果想要知道设计方法和思想,我更喜欢去看相关的文档,或直接让写代码的人跟我说说,所以,除了代码之外,我更喜欢的是与代码相关的文档设计,特别是图文并茂的文档,对于涉及复杂算法或流程的程序,如果没有文档,而只有代码,那是件非常让人痛苦的事,复杂的算法或流程是很难用注释可以表达清楚的,对此,我的原则是有文档则先看文档,代码能不看则尽量不看。
在注释的问题上,很久以前还跟我的一位同事吵过,那位同事在代码上密密麻麻地写满注释,他让我也要这样做,这让我很不能接受,因为我觉得我的代码一下就可以看明白的,不需要那么多的注释,除非他英语很差,需要我把它翻译成中文才能看明白,而且我的注释都是英文的注释,那位同事的注释是全中文的,他几乎为每一行语句都做了中文注释,让我感觉他象是在为他的代码做中文翻译,我始终觉得作为一名程序员,起码要过英语这一关,如果英语不行,可以想象他的代码可读性会非常差,他写的函数名、变量名会很难让人看明白,那只好在他的代码上密密麻麻地写满中文翻译了,但我觉得这样的程序员不是称职的程序员。为函数名、变量名取一个很容易让人看明白的名字,胜过写一大堆的注释,容易让人理解、容易让人记得住的函数名、变量名,用起来也让人舒心,在写代码中最为烦恼的是当要用某个函数或变量时,却不知道名字该怎么打出来,而且总让人记不住,我最恨有这样的函数名和变量名。
那到底什么样的注释才算是合理的呢?我觉得一方面要让程序员从繁琐的注释中解脱出来,让他能够更加关注程序的设计问题,另一方面还要确保代码的可读性。写代码也关系到做人的问题,有些人仅为自己考虑,觉得只要自己能够看得懂就可以了,殊不知在公司中写的代码是公司的,是很有可能要让其他人接手维护的,所以我们在写代码时也要为别人考虑,要站在别人角度来看自己写的代码,当觉得自己的某段代码或某行语句可能会让人很难理解时,则一定要写上足够的注释,我觉得这是为代码写注释的最基本的原则。
看别人的代码总觉得很累,代码是抽象的,不管注释再多,要把别人写的代码全部理解下来,总要死掉不少的脑细胞,所以万不得已时我一般不去看别人写的代码,除非那代码需要我去维护,如果想要知道设计方法和思想,我更喜欢去看相关的文档,或直接让写代码的人跟我说说,所以,除了代码之外,我更喜欢的是与代码相关的文档设计,特别是图文并茂的文档,对于涉及复杂算法或流程的程序,如果没有文档,而只有代码,那是件非常让人痛苦的事,复杂的算法或流程是很难用注释可以表达清楚的,对此,我的原则是有文档则先看文档,代码能不看则尽量不看。
相关文章推荐
- 在MyEclipse中写python代码的中文注释乱码问题
- [Ubuntu--VIM]vim打开代码文档中文注释显示为乱码的问题解决
- 解决 Visual Studio 中代码注释自动折叠的问题
- latex 中,代码注释含有中文和英文,英文会跑后面的问题。
- Android Studio 导入 Eclipse 的代码后,代码中的注释显示乱码问题
- 解决eclipse中java代码注释变成乱码的问题
- 【贪心算法】田忌赛马问题代码和注释
- Matlab蚁群算法解决TSP问题代码超详细注释
- UE注释的代码染色问题
- 快速解决eclipse中注释的代码依然会执行的问题
- 写C++代码遇到的一个问题,错误已经在代码中注释了
- 关于 生产者与 消费者问题 代码 ++ 注释
- 关于在OJ提交的代码里的注释问题
- 【python3问题解决】python3代码添加中文注释报错
- 关于代码加不加注释的问题
- myeclipse中java代码注释模板问题
- Android项目 手机安全卫士(代码最全,注释最详细)之十 应用程序更新的签名问题
- Android Studio 导入 Eclipse 的代码后,代码中的注释显示乱码问题
- 解决eclipse中java代码注释变成乱码的问题
- 解决eclipse中java代码注释变成乱码的问题