文档章节

【习惯的力量】- 1:如何写好你的注释?

止静
 止静
发布于 2014/10/27 21:41
字数 2228
阅读 91
收藏 0

好的习惯,是成功的一半。

你写的代码是为了给别人看的。很多人以为写的代码机器能运行就Ok了,事后出现的事情的态度:“事不关己;爱找谁找谁去,别找我就行。”为什么很多人不愿意看自己写的代码,因为自己看都困难;所以我想说的是,这样的态度,这样的作风,谁会和你合作,你一离开,这公司就得关门了。因为别人无法动弹你的代码,想看,可以,一行行来,但是没准编码编写的还不规范呢,那写的唧唧歪歪的,那就傻帽了。无从下手,还不如重写呢。你写的代码就算你能看懂,也不是给你自己看的,写代码是给别人看的。

没有良好的文档沟通,会浪费很多无聊的时间。比如你写的是c++,我写的是java,要是咱俩没有统一的文档进行沟通,那么很难交互。还有一点要说明的是,你写的代码不是为了这次允许就完成了任务了。写的代码不是为了给机器运行的。

后期的维护,其实一个项目,后期维护要花的时间远远比你写代码花的时间要多的多,这就是我们反复强调的,为什么写注释要比代码多,好的习惯应该是注释占整个篇幅的三分之二。这样维护人员对项目进行后期的维护的时候,才能很好的进行维护或者说是升级。

其实你换个角度想想也知道,要是给你的一个项目,一点注释都没有的,那么让你找错,或者让你做后期的维护;你想哭的情绪都有了我觉得。谁都不愿意看没有注释的代码,难受。好比高中的时候看古文;得一字一字的看,不懂得还得看古文的下面的注释,这样一个很费时间阅读方式。当然那是文化的结晶,你写的代码不加注释,是什么的结晶呢?

不要说时间不够,项目紧,就不写注释了;没有哪一条规定说项目紧,就不写注释的。不写注释就是死路一条。

跟大家分享一下:

写好程序注释的十三条建议

1. Comment each level(每个级别的注释有统一的风格)

注释每一个代码块,并且在各个级别的代码块上,要使用统一的注释方法。例如:

  • 对于类,应包含简单的描述、作者以及最近的更改日期

  • 对于方法,应包含目的的描述、功能、参数以及返回值

使用统一的注释规则对于一个团队是非常重要的。当然,更加推荐使用注释的约定和工具(例如,C#的XML或Java的Javadoc),它们会是注释变得更加容易。

 

2. Use paragraph comments(对段落注释)

将代码块分成若干完成独立功能的“段落”,并在每个“段落”前添加注释,向读者说明“即将发生什么”。

// Check that all data records

// are correct

foreach (Record record in records)

{

if (rec.checkStatus()==Status.OK)

{

. . .

}

}

// Now we begin to perform

// transactions

Context ctx = new ApplicationContext();

ctx.BeginTransaction();

. . .

 

3. Align comments in consecutive lines(对齐注释行)

对于拥有后缀式注释的多行代码,排版注释代码,使各行注释对齐到同一列。

const MAX_ITEMS = 10; // maximum number of packets

const MASK = 0x1F; // mask bit TCP

一些开发人员使用tab来对齐注释,有些则使用空格。但是由于tab在不同的编辑器或者IDE上会有所不同,最好还是使用空格。

 

4. Don't insult the reader's intelligence(不要侮辱读者的智商)

不要写没用的注释,例如:

if (a == 5) // if a equals 5

counter = 0; // set the counter to zero

写这种无用的注释不但浪费你的时间,而且读者在读这种很容易理解的代码时,很容易被你的注释转移注意力,浪费了时间。

 

5. Be polite(要有礼貌)

不要写不礼貌的注释代码,例如“注意,愚蠢的使用者输入了一个负数”,或者“修正由于最初的开发者的可怜且愚蠢的编码所造成的副作用”。这样的注释冒犯了作者,而且你并不知道谁会在将来读到这段注释——你老板、客户或者是你在注释中冒犯的那个可怜且愚蠢的开发人员。

 

6. Get to the point(简明扼要)

不要在注释中写的过多,不要写玩笑、诗和冗长的话。总之,注释需要简单直接。

 

7. Use a consistent style(风格一致)

一些人认为注释应该能让非程序员也能看懂,但是也有些人认为注释仅仅是指导程序员的。不管怎么说,像《Successful Strategies for Commenting Code》中所说,真正重要的是注释始终面向同一个读者,在这点上,应该保持一致。个人认为,我很怀疑会有非程序人员阅读代码,所以应该把阅读注释的对象定位为开发人员。

 

8. Use special tags for internal use(在内部使用特殊的标签)

团队中处理代码时,在程序员之间应采用一系列统一的‘标签注释’进行交流。例如,很多团队使用“TODO”来表示一段需要额外工作的代码。

int Estimate(int x, int y)

{

// TODO: implement the calculations

return 0;

}

‘标签注释’并不解释代码,而是引起主意或者传递信息。但是,使用这种方法时,务必要完成‘标签注释’传递的信息。

 

9. Comment code while writing it(写代码的同时,完成注释)

写代码的同时添加注释,因为此时你的思路最为清晰。如果你把注释的任务留到最后,那么你相当于经历了两次编码。“我没有时间注释”“我太忙了”“项目耽误了”这些往往是不写注释的理由。所以,程序员们认为,最理想的解决方法是‘写代码前先写注释’。例如:

public void ProcessOrder()

{

// Make sure the products are available

// Check that the customer is valid

// Send the order to the store

// Generate bill

}

 

10. Write comments as if they were for you (in fact, they are)把代码的读者想象成你自己(实际情况往往如此)

注释代码时,不仅仅要为将来可能维护你代码的人考虑,而且要考虑到读注释的可能是你。伟大的Phil Haack说过:“每当有一行代码被敲上屏幕,你都要从维护的角度审视一遍这段代码。” "As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code."(著名的话不敢不附上原句)

结果,我们自己往往是我们良好注释的受益者,或者是烂注释的受害人。

 

11. Update comments when you update the code(更新代码时,记得更新注释)

如果不能随着代码的更新而更新注释,那么即使再准确的注释也毫无意义。代码和注释必须同步,否则这些注释对于维护你代码的程序人员来说简直是折磨。在使用refactoring工具自动更新代码时,应尤其注意,它们会自动更新代码而不会改变注释,这些注释自然就过期了。

 

12. The golden rule of comments: readable code(可读性良好的代码是最好的注释)

对于许多程序员来说,基本的原则之一就是:让代码自己说话。有人可能会怀疑这是那些不爱写注释的程序员的借口,然而这确实是一个不争的事实。自我解释良好的代码对于编码来说大有益处,不但代码容易理解甚至使注释变得没有必要。举例来说,在我的文章《Fluid Interfaces》中展示了什么是清晰的自我解释型代码:

Calculator calc = new Calculator();

calc.Set(0);

calc.Add(10);

calc.Multiply(2);

calc.Subtract(4);

Console.WriteLine( "Result: {0}", calc.Get() );

在本例中,注释是没必要的,并且会违背tip#4 。为了使代码更加可读,应该考虑使用适当的名字(像在经典的《Ottinger's Rules》描述的),确保正确的缩进和代码风格栏线(代码风格栏线是类似于#region #endregion这类的东西吧?)。如果这一点做的不好,直接后果是,你的注释看起来就像是在为晦涩难懂的代码而道歉。

你也许也有亲身体会,没有注释的代码,你愿意看吗?好的习惯,决定着你的未来。


© 著作权归作者所有

止静
粉丝 121
博文 134
码字总数 125762
作品 0
东城
技术主管
私信 提问
写好注释的方法小结

关于如何写好代码注释: 注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。 程序中,真实只存在一处地方:代码。应该尽量使用代码表达,而尽量减少注释。 什么样的注释才是好的注释:...

Freewheel
2015/11/28
120
0
测试用例注解testcase-annotation

支持通过@testcase编写用例,最后自动导出成excel或者html. 在传统测试流程中,我们一般在EXCEL或其他用例管理系统中把用例写好,然后逐条实现测试脚本,最后把写好的用例复制到代码的注释中...

stroller
2013/08/06
2.5K
0
Eclipse/MyEclipse注释模板和格式化模板的使用

在一个项目的完整的生命周期中,其维护费用,往往是其开发费用的数倍。因此项目的可维护性、可复用性是衡量一个项目好坏的关键。而注释则是可维护性中必不可少的一环。 注释模板导入步骤 安装...

Carl_
2015/06/09
718
0
『No17: gin-swagger 构建自动化文档』

大家好,我叫谢伟,是一名程序员。 今天的主题:Swagger API 文档 首先问个问题, API 文档重不重要? 重要,前后端的交互一般流程是这样的,后端暴露出API后,交给前端,前端根据API的响应,...

谢小路
2018/07/23
0
0
Effective Dart 文档注释在Flutter项目中的实践

前言 什么是注释? 在编程语言中,注释就是对代码的解释和说明,其目的是让人们能够更加轻松地了解代码。 也有一句话是这样说的:程序员都讨厌两件事,1.别人不写注释 2.自己写注释 在开发者...

ditclear
04/11
0
0

没有更多内容

加载失败,请刷新页面

加载更多

sync 包讲解

sync.Once Once 的作用是多次调用但只执行一次,Once 只有一个方法,Once.Do(),向 Do 传入一个函数,这个函数在第一次执行 Once.Do() 的时候会被调用,以后再执行 Once.Do() 将没有任何动作...

李琼涛
3分钟前
1
0
java中的byte占一字节或4字节

https://www.jianshu.com/p/2f663dc820d0

南桥北木
17分钟前
2
0
Cassandra 常用命令

Linux控制台命令 #进入Cassandra的安装目录 cd /home/db/cassandra/cassandra #进入Cassandra 无密码 ./bin/cqlsh localhost(IP)有密码 ./bin/cqlsh localhost(IP)-u 用户名 #显示所...

最菜最菜之小菜鸟
22分钟前
2
0
自建redis笔记

自建redis笔记 最近在linux安装了一下redis,特做一些笔记! 本文先单节点启动redis,然后再进行持久化配置,在次基础上,再分享搭建主从模式的配置以及Sentinel 哨兵模式及集群的搭建 单节点...

北极之北
30分钟前
2
0
扛住阿里双十一高并发流量,Sentinel是怎么做到的?

Sentinel 承接了阿里巴巴近 10 年的双十一大促流量的核心场景 本文介绍阿里开源限流熔断方案Sentinel功能、原理、架构、快速入门以及相关框架比较 基本介绍 1 名词解释 服务限流 :当系统资源...

分布式系统架构
38分钟前
6
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部