学习笔记:注释
2015-06-09 17:16
204 查看
代码注释,可以说是比代码本身更重要。这里有一些方法可以确保你写在代码中的注释是友好的:
不要重复阅读者已经知道的内容
能明确说明代码是做什么的注释对我们是没有帮助的。
要注释说明推理和历史
如果代码中的业务逻辑以后可能需要更新或更改,那就应该留下注释:)
同一行的注释不要写得很长
没什么比拖动水平滚动条来阅读注释更令开发人员发指的了。事实上,大多数开发人员都会选择忽略这类注释,因为读起来真的很不方便。
要把长注释放在逻辑上面,短注释放在后面
注释如果不超过120个字符那可以放在代码旁边。否则,就应该直接把注释放到语句上面。
不要为了注释而添加不必要的注释
画蛇添足的注释会造成混乱。也许在学校里老师教你要给所有语句添加注释,这会帮助开发人员更好地理解。但这是错的。谁要这么说,那你就立马上给他个两大耳刮子。代码应该保持干净简洁,这是毋庸置疑的。如果你的代码需要逐行解释说明,那么你最需要做的是重构。
注释要拼写正确
不要为代码注释中的拼写错误找借口。IDE可以为你检查拼写。如果没有这个功能,那就去下载插件,自己动手!
要多多练习
熟能生巧。试着写一些有用的注释,可以问问其他开发人员你的注释是否有用。随着时间的推移,你会慢慢懂得怎样才算是友好的注释。
要审查别人的注释
在代码审查时,我们往往会忽略查看注释。不要怕要求更多的注释,你应该提出质疑。如果每个人都养成写好注释的好习惯,那么世界将会更美好。
总结
注释是开发进程中非常重要的一部分,但我们不应该为了注释而注释。注释应该是有用的,简洁的,应该是对代码的一种补充。注释不应该用于逐行地解释代码,相反,它应该用于解释业务逻辑,推理以及对将来的启示。
不要重复阅读者已经知道的内容
能明确说明代码是做什么的注释对我们是没有帮助的。
如果代码中的业务逻辑以后可能需要更新或更改,那就应该留下注释:)
没什么比拖动水平滚动条来阅读注释更令开发人员发指的了。事实上,大多数开发人员都会选择忽略这类注释,因为读起来真的很不方便。
注释如果不超过120个字符那可以放在代码旁边。否则,就应该直接把注释放到语句上面。
画蛇添足的注释会造成混乱。也许在学校里老师教你要给所有语句添加注释,这会帮助开发人员更好地理解。但这是错的。谁要这么说,那你就立马上给他个两大耳刮子。代码应该保持干净简洁,这是毋庸置疑的。如果你的代码需要逐行解释说明,那么你最需要做的是重构。
不要为代码注释中的拼写错误找借口。IDE可以为你检查拼写。如果没有这个功能,那就去下载插件,自己动手!
要多多练习
熟能生巧。试着写一些有用的注释,可以问问其他开发人员你的注释是否有用。随着时间的推移,你会慢慢懂得怎样才算是友好的注释。
要审查别人的注释
在代码审查时,我们往往会忽略查看注释。不要怕要求更多的注释,你应该提出质疑。如果每个人都养成写好注释的好习惯,那么世界将会更美好。
总结
注释是开发进程中非常重要的一部分,但我们不应该为了注释而注释。注释应该是有用的,简洁的,应该是对代码的一种补充。注释不应该用于逐行地解释代码,相反,它应该用于解释业务逻辑,推理以及对将来的启示。
相关文章推荐
- 2012年"浪潮杯"山东省第三届ACM大学生程序设计竞赛--n a^o7 ! 分类: 比赛 2015-06-09 17:16 14人阅读 评论(0) 收藏
- Linux mysql常用操作命令
- Spring HTTP Invoker 学习小记
- leetcode-56&88 Merge Intervals && Merge Sorted Array
- AUTOCAD ActiveX 设置默认点样式
- <转载>Win x86-64 - Download & execute (Generator)
- MapReduce之三—搜索引擎-倒排索引实现
- utf8转为gb2312的函数
- 安装使用percona版本mysql
- 《C++语言基础》实践参考——二进制文件浏览器
- 手机端iscoll插件的使用方法
- 把视频秒数转换成时间格式输出
- Spring HTTP invoker简介
- 用Mouse_event()来控制鼠标操作
- JavaBean 中的属性详解(实例)
- art.dialog
- 测试驱动开发(TDD)及测试框架Mocha.js入门学习
- C# 堆栈和堆 Heap & Stack
- [LeetCode] Largest Number
- MySQL集群搭建步骤详解