很多程序员在写代码的时候往往都不注意代码的可读性,让别人在阅读代码时花费更多的时间。其实,只要程序员在写代码的时候,注意为代码加注释,并以合理的格式为代码加注释,这样就方便别人查看代码,也方便自己以后查看了。下面分享十个加注释的技巧:
1. 逐层注释
为每个代码块添加注释,并在每一层使用统一的注释方法和风格。例如:
- 针对每个类:包括摘要信息、作者信息、以及最近修改日期等;
- 针对每个方法:包括用途、功能、参数和返回值等。
在团队工作中,采用标准化的注释尤为重要。当然,使用注释规范和工具(例如C#里的XML,Java里的Javadoc)可以更好的推动注释工作完成得更好。
2. 使用分段注释
如果有多个代码块,而每个代码块完成一个单一任务,则在每个代码块前添加一个注释来向读者说明这段代码的功能。例子如下:
03 |
foreach (Record record in records) |
05 |
if (rec.checkStatus()==Status.OK)
|
12 |
Context ctx = new ApplicationContext();
|
13 |
ctx.BeginTransaction(); |
3. 在代码行后添加注释
如果多行代码的每行都要添加注释,则在每行代码后添加该行的注释,这将很容易理解。例如:
在分隔代码和注释时,有的开发者使用tab键,而另一些则使用空格键。然而由于tab键在各编辑器和IDE工具之间的表现不一致,因此最好的方法还是使用空格键。
4. 不要侮辱读者的智慧
避免以下显而易见的注释:写这些无用的注释会浪费你的时间,并将转移读者对该代码细节的理解。
3 |
website = "http://www.hualai.net.cn" ; // this is a website
|
5. 礼貌点
避免粗鲁的注释,如:“注意,愚蠢的使用者才会输入一个负数”或“刚修复的这个问题出于最初的无能开发者之手”。这样的注释能够反映到它的作者是多么的拙劣,你也永远不知道谁将会阅读这些注释,可能是:你的老板,客户,或者是你刚才侮辱过的无能开发者。
6. 关注要点
不要写过多的需要转意且不易理解的注释。避免ASCII艺术,搞笑,诗情画意,hyperverbosity的注释。简而言之,保持注释简单直接。
7. 使用一致的注释风格
一些人坚信注释应该写到能被非编程者理解的程度。而其他的人则认为注释只要能被开发人员理解就行了。无论如何,Successful Strategies for Commenting Code已经规定和阐述了注释的一致性和针对的读者。就个人而言,我怀疑大部分非编程人员将会去阅读代码,因此注释应该是针对其他的开发者而言。
8. 使用特有的标签
在一个团队工作中工作时,为了便于与其它程序员沟通,应该采用一致的标签集进行注释。例如,在很多团队中用TODO标签表示该代码段还需要额外的工作。
1 |
int Estimate( int x, int y)
|
注释标签切忌不要用于解释代码,它只是引起注意或传递信息。如果你使用这个技巧,记得追踪并确认这些信息所表示的是什么。
9. 在代码时添加注释
在写代码时就添加注释,这时在你脑海里的是清晰完整的思路。如果在代码最后再添加同样注释,它将多花费你一倍的时间。而“我没有时间写注释”,“我很忙”和“项目已经延期了”这都是不愿写注释而找的借口。一些开发者觉得应该write comments before code,用于理清头绪。例如:
1 |
public void ProcessOrder()
|
10. 为自己注释代码
当注释代码时,要考虑到不仅将来维护你代码的开发人员要看,而且你自己也可能要看。用Phil Haack大师的话来说就是:“一旦一行代码显示屏幕上,你也就成了这段代码的维护者”。因此,对于我们写得好(差)的注释而言,我们将是第一个受益者(受害者)。
分享到:
相关推荐
代码 辅助 注释 代码 辅助 注释代码 辅助 注释代码 辅助 注释代码 辅助 注释
程序员佛祖代码注释,佛祖保佑,代码无BUG
聪哥创作的一款批量保留路径清理代码注释的工具,目前兼容大部分常见的代码注释,涵盖c、java、python、php、js、html、css、mysql、node、vue、ruby等常见编程项目的注释无损清理。 2023年8月19日更新日志: 1.对...
主要介绍了提高代码可读性的十大注释技巧,详细分析了编程开发中常用的代码注释方法,需要的朋友可以参考下
去除源代码注释,去除java源代码注释.
提高代码可读性的10个注释技巧,sunshine1028,即日启程,李鸿明
Eclipse 代码注释模板 Eclipse 代码注释模板 Eclipse 代码注释模板 Eclipse 代码注释模板
LibSVM-2.6程序代码注释
C++代码文档生成器 根据代码及注释自动生成代码文档.zip
代码注释检测工具,用于进行代码注释统计,非常不错的哦。
linecount可以统计代码注释率注释行/代码行X100%和同行代码走读判断注释的有效性。 注意:在自动统计过程中,也要配合人工抽查,是否注释明确。
SWFUPLoad 所有图标和代码注释汉化文件SWFUPLoad 所有图标和代码注释汉化文件SWFUPLoad 所有图标和代码注释汉化文件SWFUPLoad 所有图标和代码注释汉化文件SWFUPLoad 所有图标和代码注释汉化文件SWFUPLoad 所有图标和...
Java代码注释率检查器
LIO-SAM代码阅读详细注释版,2020年11月1日下载版本。目前还有部分没懂,以后再更新,博客里有相应的文章,文章里的注释和这里是一样的,不能保证能够运行,有可能写注释的时候不小心改了代码。
完全使用Spring实现的增删改查 核心是SpringMVC 你懂得 每一句都带注释 看懂代码很轻松!技术是要分享的 越分享越快乐
小米便签的源代码及详细注解,可供新学Java的同学借鉴代码风格
1. 同名博客:手把手教你使用SHAP 2. 实例讲解,包括(数据+代码+注释) 3. 可自定义图的标签、字体大小等设置 4. 基于jupyter,python代码,可直接运行 5. 若有疑问,可在同名博客...
注释代码技巧 c#中 很详细的文章 !! 适合初学者学习
此工具为本人自己写的一个sourceinsight宏代码,可以方便的完成单行或多行代码的C语言风格以及#if 0方式的注释和去注释,附使用说明,需要的可以下载
代码整理小工具,快速清除代码中注释,申请软著必备小工具