13个代码注释的小贴士
下面的13条小贴士可以帮助你写出更规范、更容易维护的代码注释。
1、逐层注释
使用统一格式对每一个语句块进行注释,如:
- 类:简单描述、作者、最后修改时间等
- 方法:关于该方法的目的、函数、参数、返回值的描述
在团队工作中,使用统一的注释规范显得尤为重要。当然,也推荐使用一些专门用来添加代码注释的工具,如C#中的XML、Java中的Javadoc等。
2、使用段落型注释
将代码分割成能完成独立任务的段落,并在其前后添加注释,告诉读者程序将要做什么。
// 检查所有的记录是否正确
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// 现在开始进行事务处理
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .
3、对齐连续的行注释
若对多行添加行末注释,应将注释进行对齐,以便于阅读。
const MAX_ITEMS = 10; //
数据包的最大数量
const MASK = 0x1F; //
TCP标志位
有些程序远使用制表符来进行对齐,有些则使用空格。建议使用空格来对齐,因为不同的代码编辑器对制表符的处理会不一样。
4、不要侮辱读者的智商
不要用这样的注释:
if (a == 5) // 如果a等于5
counter = 0; // 就将counter的值赋为0
这样做只会浪费你的时间,而且读者的注意力会被从代码中转移。
5、注意礼貌
避免使用无礼的注释,如:注意有些蠢蛋会输入一个负数;这修复了程序最初版本遇到的问题,那个无个救药的笨蛋。这样的注释会反映作者的素质,而且你不知道将来谁会读到你的程序:你的老板、顾客,或者是你刚才辱骂过的那个程序员。
6、讲重点
不要在写冗余的注释,也不要用所谓的字符艺术、玩笑、小诗等。总之要保持注释的简单和直接。
7、坚持统一风格
有些人认为代码注释应该简单到让不会编程的人也能看懂,另一些人则认为代码注释只要让程序员看懂就可以了。不管怎样,正如《撰写代码注释的成功策略 》中所提到的,代码注释的风格应该是固定的,是为同一个观众准备的。而且我个人认为不太会有非程序员来阅读代码,所以代码注释应该只是针对其他程序员的。
8、使用内部统一规定的标签
在进行团队开发时,可以在注释中使用一些特殊的标签。比如在一些团队中使用“TODO:“标签来表示这里还需要完成其他的一些任务。
int Estimate(int x, int y)
{
// TODO: 实现这项计算
return 0;
}
这里所使用的标签注释并不是用来解释代码,而是引起读者注意并传递一些信息。如果你的团队确实在使用这类注释,就要保证会依此进行作业。
9、边写代码边注释
在写代码的时候,乘脑中记忆还清晰,及时写上注释。如果你想在程序编写完之后再添加注释,也许就会花费你两倍的时间。“我没有时间添加注释”、“我很忙”、“这个项目已经有所拖延了”都将会是你的借口。有些程序员认为你应该在编写代码之前就写好注释 ,以为你的最终方案作出计划。如:
public void ProcessOrder()
{
// 保证这些产品是可以购买得到的
// 检查用户时候合法
// 向商店发出订单
// 生成账单
}
10、就当是为自己写注释(事实上的确是让你自己看的)
在添加代码注释时,要想到这些注释不仅是为将来维护代码的程序员而写,也是为你自己而写。用伟大的Phil Haack 的话来说:“当一行代码写好并出现在屏幕上时,你就变成了一名维护人员。”所以,我们自己将会成为代码注释的第一个受益人或受害者。
11、更新代码时同时更新注释
如果注释不随着代码的改变而修改,那在准备的注释也是没有用的。代码和注释应该始终保持同步,否则这些文不对题的注视将使维护人员摸不着头脑。对于那些自动添加注释的工具要格外注意,不要让它忽略更新注释。
12、黄金准则:写可读的代码
有一条基本准备叫“让代码解释它自己”。虽然有人认为这个倡议是由一个懒得写注释的程序提出的,但不可否认的是一条可以自我解释的代码可以让其变得更为易懂,并让注释显得不那么重要。如,在我的Fluid Interfaces 文章中有一些可以自我解释的代码的例子:
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );
在这个例子中,代码不需要注释,否则会违反本文的第四条贴士。要写出可读的代码,你应该考虑使用恰当的名称(在Ottinger's Rules 中有所叙述),确保标识正确,并根据代码规范 来撰写。如果没有遵循此条建议,注释可能会被看作是代码的一种“道歉”。
13、和你的同事分享这些贴士
虽然第10条贴士说我们自己将是代码注释的第一个受益者,但如果把这些贴士分享给你的同事,尤其是在同一个团队中工作的同事,你就会发现你们写出的代码注释会更为易懂和易于维护。
13个代码注释的小贴士相关推荐
- 13个代码注释的小技巧
13个代码注释的小技巧 这篇文章是由José M. Aguilar在他卓越的博客中以西班牙语的形式首发,其后Timm Martin在获得Aguilar先生的授权下,对该文章进行翻译.修改,并且在D ...
- 十三个代码注释的小技巧
1. 对不同级别的代码进行注释 对于不同级别的代码块,要使用统一的方法来进行注释.例如: 对于每一个类,需要包含一段简明扼要的描述,作者和上一次修改的时间 对于每一个方法,需要包含这个方法的用途,功能 ...
- 代码注释(图案:小狗)
代码如下: /*_.'__ `..--($)($$)---/#\.' @ /###\: , #####`-..__.-' _.-\###/`;_: `"'.'""&quo ...
- [原创]jQuery推箱子小游戏(100关且可扩展可选关),休闲,对战,娱乐,小游戏,下载即用,兼容iPad移动端,代码注释全(附源码)
Sokoban 介绍 [原创]jQuery推箱子小游戏(100关且可扩展可选关),休闲,对战,娱乐,小游戏,下载即用,兼容iPad移动端,代码注释全(附源码) 游戏说明 经典的推箱子是一个来自日本的古 ...
- 【小知识】有趣代码注释图案【持续收集更新...】
滑稽 滑稽 滑稽 滑稽 滑稽代码注释 /*** * .,, .,:;;iiiiiiiii;;:,,. .,, * rGB##HS,.;iirrrrriiiiiiiiiirrrrri;,s&## ...
- yolov3网络结构图_目标检测——YOLO V3简介及代码注释(附github代码——已跑通)...
GitHub: liuyuemaicha/PyTorch-YOLOv3github.com 注:该代码fork自eriklindernoren/PyTorch-YOLOv3,该代码相比master分 ...
- Python代码注释 - Python零基础入门教程
目录 一.什么是代码注释 二.为什么写代码要注释 三.代码注释的方式 1.单行注释,使用英文符号 # 2.多行注释 方法一:英文状态下使用单引号 """ 方法二:英文状态 ...
- git 如何忽略掉文件夹_#PY小贴士# 我的git仓库为什么每次提交都有很多改动?
git 是如今最流行的代码版本管理工具,没有之一. 今天说一个 git 使用时的细节:.gitignore 我们在使用 git 管理代码时,如果默认把项目里的所有文件都 add 进去,加入到仓库中,会 ...
- 超有意思的代码注释_程序员搞笑的代码注释:谁的代码注释我都不服,就服你的...
什么是代码注释,如何在代码中添加注释,相信每一位了解编程的人并不陌生.注释里往往有很多有趣的脑洞和「真心话」.今天我们一起去看看那些6到飞起,被玩坏了的幽默注释吧. 信息量太大的注释系列-- 01 你 ...
最新文章
- 使用Altera综合工具Quartus II下载到FPGA时无法识别USB-Blaster问题
- jQuery基础 (一)—样式篇
- Yii的beforeAction
- linux修改网卡文件夹,CentOS7 修改网卡名称为eth0在VMWare中添加多网卡配置
- 《Java8实战》笔记汇总
- 类 workbooks 的 open 方法无效_第十九章 Cach 命令大全 OPEN 命令
- 语言的开题报告范文_【开题系列】刘凤朝:撰写文科博士学位论文开题报告应注意的几个问题...
- 系统类配置(三)【ubuntu14.04或者ubuntu16.04 配置caffe】
- paip.mysql备份慢的解决
- image target behaviour 和image target的关系_图片分析软件Image-Pro Plus的基础操作
- 对计算机硬盘进行格式化时,在安装操作系统之前,如何对硬盘进行分区和格式化(新手必看)...
- 二阶带通滤波器电路设计
- 悼念前端大牛司徒正美
- 高效能人士的七个习惯读后感与总结概括-(第四章)
- IaaS(基础设施即服务),PaaS(平台即服务),SaaS(软件即服务)的区别
- 房地产微信营销方案微信“危”与“机”
- 【0005】删除文件时,提示你需要权限才能执行此操作
- 2. 表的操作:创建表、修改表、列约束和表约束、数据操作、删除表
- vue el-table高度 height自适应
- 五分钟学会python函数_Python——带你五分钟了解函数式编程与闭包
热门文章
- C语言 第五章 循环结构
- 装饰器前奏2(2017年8月23日 11:50:39)(2017年8月29日 16:07:32)
- 制作一个功能丰富的Android天气App
- bzoj1878: [SDOI2009]HH的项链
- linux 编译java并打包
- php5.3开始出现的Function ereg() is deprecated Error问题解决办法
- 成为编程高手的二十二条军规
- undo自动调优介绍
- tomcat部署web應用時涉及到的基本概念
- 实现IFrame的自适应高度