很多程序员在写代码的时候往往都不注意代码的可读性,让别人在阅读代码时花费更多的时间。其实,只要程序员在写代码的时候,注意为代码加注释,并以合理的格式为代码加注释,这样就方便别人查看代码,也方便自己以后查看了。下面分享十个加注释的技巧:
1. 逐层注释
为每个代码块添加注释,并在每一层使用统一的注释方法和风格。例如:
针对每个类:包括摘要信息、作者信息、以及最近修改日期等;
针对每个方法:包括用途、功能、参数和返回值等。
在团队工作中,采用标准化的注释尤为重要。当然,使用注释规范和工具(例如C#里的XML,Java里的Javadoc)可以更好的推动注释工作完成得更好。
2. 使用分段注释
如果有多个代码块,而每个代码块完成一个单一任务,则在每个代码块前添加一个注释来向读者说明这段代码的功能。例子如下:
// 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. 在代码行后添加注释
如果多行代码的每行都要添加注释,则在每行代码后添加该行的注释,这将很容易理解。例如:
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
在分隔代码和注释时,有的开发者使用tab键,而另一些则使用空格键。然而由于tab键在各编辑器和IDE工具之间的表现不一致,因此最好的方法还是使用空格键。
4. 不要侮辱读者的智慧
避免以下显而易见的注释:写这些无用的注释会浪费你的时间,并将转移读者对该代码细节的理解。
if (a == 5) // if a equals 5
counter = 0; // set the counter to zero
5. 礼貌点
避免粗鲁的注释,如:“注意,愚蠢的使用者才会输入一个负数”或“刚修复的这个问题出于最初的无能开发者之手”。这样的注释能够反映到它的作者是多么的拙劣,你也永远不知道谁将会阅读这些注释,可能是:你的老板,客户,或者是你刚才侮辱过的无能开发者。
6. 关注要点
不要写过多的需要转意且不易理解的注释。避免ASCII艺术,搞笑,诗情画意,hyperverbosity的注释。简而言之,保持注释简单直接。
7. 使用一致的注释风格
一些人坚信注释应该写到能被非编程者理解的程度。而其他的人则认为注释只要能被开发人员理解就行了。无论如何,Successful Strategies for Commenting Code已经规定和阐述了注释的一致性和针对的读者。就个人而言,我怀疑大部分非编程人员将会去阅读代码,因此注释应该是针对其他的开发者而言。
8. 使用特有的标签
在一个团队工作中工作时,为了便于与其它程序员沟通,应该采用一致的标签集进行注释。例如,在很多团队中用TODO标签表示该代码段还需要额外的工作。
int Estimate(int x, int y)
...{
// TODO: implement the calculations
return 0;
}
注释标签切忌不要用于解释代码,它只是引起注意或传递信息。如果你使用这个技巧,记得追踪并确认这些信息所表示的是什么。
9. 在代码时添加注释
在写代码时就添加注释,这时在你脑海里的是清晰完整的思路。如果在代码最后再添加同样注释,它将多花费你一倍的时间。而“我没有时间写注释”,“我很忙”和“项目已经延期了”这都是不愿写注释而找的借口。一些开发者觉得应该write comments before code,用于理清头绪。例如:
public void ProcessOrder()
...{
// Make sure the products are available
// Check that the customer is valid
// Send the order to the store
// Generate bill
}
10. 为自己注释代码
当注释代码时,要考虑到不仅将来维护你代码的开发人员要看,而且你自己也可能要看。用Phil Haack大师的话来说就是:“一旦一行代码显示屏幕上,你也就成了这段代码的维护者”。因此,对于我们写得好(差)的注释而言,我们将是第一个受益者(受害者)。
感谢:http://www.webspherechina.net/?viewnews-51430.html
分享到:
相关推荐
提高代码可读性的10个注释技巧,sunshine1028,即日启程,李鸿明
主要介绍了提高代码可读性的十大注释技巧,详细分析了编程开发中常用的代码注释方法,需要的朋友可以参考下
能够撰写清晰、规范的注释,提高代码可读性和维护性。 阅读建议 为了更好地理解和掌握本文所介绍的内容,建议您: 仔细阅读并理解每种注释的语法和用法; 在编写代码时积极添加合适的注释,提高代码可读性; 阅读...
本书关注编码的细节,总结了很多提高代码可读性的小技巧,看似都微不足道,但是对于整个软件系统的开发而言,它们与宏观的架构决策、设计思想、指导原则同样重要。编码不仅仅只是一种技术,也是一门艺术,编写可读性...
它们能够很好的给我们提供方便的代码注释功能。以下我们谈谈在IDE和其它工具写注释的标准和方法。我们来看如下实例:我们在自定义函数体中的注释可以在使用该函数时被预览到,甚至可以在其它文件中进行预览。下面是...
2.3 增加代码可读性——注释 2.4 提高重用性——公共组件和私有组件的维护 2.5 冗余和精简的矛盾——选择集中还是选择分散 2.6 磨刀不误砍柴工——前期的构思很重要 2.7 制订规范 2.8 团队合作的最大难度不是...
平时在我们编程过程中积累了大量的技巧和心得,可是多起来就不好管理了。这个程序帮助方便管理我们的各种技巧和资料,支持Pascal、C/C++、C#、...并且可以把代码的关键词、注释、数字符号标明出来,进一步增加可读性。
下面列出四则技巧提高CSS文件可维护性的方法,以此作为指南,以一种较好的CSS样式组织习惯来进行WEB前端开发。 一、CSS样式文件分解 对于小项目,在写代码之前,按页面结构或页面内容将代码分为几块并给予注释。...
Google JavaScript编码规范指南是Google公司推出的一套详尽且实用的JavaScript编程规范,旨在为开发者提供一个清晰、一致的编码标准,以提高代码质量、可读性和可维护性。这套规范不仅涵盖了JavaScript语言的基础...
Android腾讯微博客户端源代码,大公司的Java程序,代码编写规范、注释丰富,可读性强,学习价值高。腾讯微博程序在Andorid程序中也算比较流行的程序,通过这个源代码你或许会学习到一些意想不到的Java Android编程...
可读性:代码有大量注释。PRML 中相应的公式都有注释。符号与本书同步。 通过运行以下命令将包下载到本地文件夹(例如 ~/PRMLT/): git clone https://github.com/PRML/PRMLT.git 运行 Matla并导航到文件夹 (~/...
这意味着,在查看代码时,关键字、变量名、注释等都会以不同的颜色显示,从而提高代码的可读性。 四、Null's Notebook “Null's Notebook”是这份函数大全的品牌标识,代表着Null对C语言的热爱和对知识分享的执着...
此外,本源码在编写过程中充分考虑了代码的可读性和可维护性,采用了清晰的模块化设计,方便开发者进行调试和修改。同时,源码中的注释也详细说明了各个模块的功能和实现原理,有助于初学者快速掌握C语言编程技巧。 ...
matlab 图像膨胀代码介绍 ...可读性:代码被大量注释。 PRML 中的相应公式有注释。 符号与书同步。 实用:该包不仅可读,而且易于使用和修改以促进 ML 研究。 这个包中的许多函数已经被广泛使用(参见
在实现过程中,项目注重代码的可读性和可维护性,采用了规范的命名规则和注释方式,使得代码易于理解和维护。同时,也充分考虑了性能优化和异常处理等方面的问题,确保系统在运行过程中的稳定性和高效性。 该项目的...
注释对于代码的可读性和维护都非常重要。 2. 变量:Python是动态类型语言,可以直接赋值,不需要事先声明变量的类型。变量名由字母、数字和下划线组成,不能以数字开头。 3. 数据类型:常用的数据类型包括整型(int)...
高效:应用了许多加速Matlab代码的技巧(例如矢量化,矩阵分解等)。 通常,此软件包中的函数比Matlab内置函数(例如kmeans)的订购速度更快。 鲁棒性:应用了许多数值稳定性技巧,例如对数域中的计算概率,平方根...
此外,该项目源代码完整且规范,注释清晰,便于阅读和理解。代码结构合理,遵循了面向对象的设计原则,具有良好的可读性和可维护性。这为其他开发者提供了宝贵的参考和学习资源,同时也为项目的二次开发定制奠定了...