提高代码可读性的注释技巧 实用型

很多程序员在写代码的时候往往都不注意代码的可读性,让别人在阅读代码时花费更多的时间。其实,只要程序员在写代码的时候,注意为代码加注释,并以合理的格式为代码加注释,这样就方便别人查看代码,也方便自己以后查看了。下面分享十个加注释的技巧:
为每个代码块添加注释,并在每一层使用统一的注释方法和风格。例如:
· 针对每个类:包括摘要信息、作者信息、以及最近修改日期等;
· 针对每个方法:包括用途、功能、参数和返回值等。
在团队工作中,采用标准化的注释尤为重要。当然,使用注释规范和工具(例如C#里的XML,Java里的Javadoc)可以更好的推动注释工作完成得更好。
如果有多个代码块,而每个代码块完成一个单一任务,则在每个代码块前添加一个注释来向读者说明这段代码的功能。
例子如下:
// 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();
. . .
如果多行代码的每行都要添加注释,则在每行代码后添加该行的注释,这将很容易理解。例如:
const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP
在分隔代码和注释时,有的开发者使用tab键,而另一些则使用空格键。然而由于tab键在各编辑器和IDE工具之间的表现不一致,因此最好的方法还是使用空格键。
避免以下显而易见的注释:写这些无用的注释会浪费你的时间,并将转移读者对该代码细节的理解。
if (a == 5) // if a equals 5
counter = 0; // set the counter to zero
避免粗鲁的注释,如:“注意,愚蠢的使用者才会输入一个负数”或“刚修复的这个问题出于最初的无能开发者之手”。这样的注释能够反映到它的作者是多么的拙劣,你也永远不知道谁将会阅读这些注释,可能是:你的老板,客户,或者是你刚才侮辱过的无能开发者。
不要写过多的需要转意且不易理解的注释。避免ASCII艺术,搞笑,诗情画意,hyperverbosity的注释。简而言之,保持注释简单直接。
一些人坚信注释应该写到能被非编程者理解的程度。而其他的人则认为注释只要能被开发人员理解就行了。无论如何,Successful Strategies for Commenting Code已经规定和阐述了注释的一致性和针对的读者。就个人而言,我怀疑大部分非编程人员将会去阅读代码,因此注释应该是针对其他的开发者而言。
在一个团队工作中工作时,为了便于与其它程序员沟通,应该采用一致的标签集进行注释。例如,在很多团队中用TODO标签表示该代码段还需要额外的工作。
int Estimate(int x, int y)
...{
// TODO: implement the calculations
return 0;
注释标签切忌不要用于解释代码,它只是引起注意或传递信息。如果你使用这个技巧,记得追踪并确认这些信息所表示的是什么。
在写代码时就添加注释,这时在你脑海里的是清晰完整的思路。如果在代码最后再添加同样注释,它将多花费你一倍的时间。而“我没有时间写注释”,“我很忙”和“项目已经延期了”这都是不愿写注释而找的借口。一些开发者觉得应该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
当注释代码时,要考虑到不仅将来维护你代码的开发人员要看,而且你自己也可能要看。用Phil Haack大师的话来说就是:“一旦一行代码显示屏幕上,你也就成了这段代码的维护者”。因此,对于我们写得好(差)的注释而言,我们将是第一个受益者(受害者)。

原文地址:https://blog.51cto.com/14512197/2437767

时间: 2024-11-29 09:14:12

提高代码可读性的注释技巧 实用型的相关文章

如何提高代码可读性

一.要提高的代码的可读性,可以从以下几方面努力 1. 清晰地表达意图 2.好的变量.方法.类名 3. 一个变量.类.方法只做一件事 4. 同一个方法体内,保持相同的抽象层次 5.一致的缩进,一致的格式 6. 不要重复自己(避免手动的复制与粘贴代码) 7. 减少“语法噪音” 8.减少代码中的嵌套级别 9. 命名时取有意义的名字,避免不规范的缩写 二.具体的提高代码的可读性的做法 1.先写注释,再写代码:理清思路再动手 (1)清晰的思路是编程行动的良好指南 花点时间思考一下,不要一接到任务就动手编代

Unity3d 基本设计开发 原则(提高代码可读性)

参考:http://blog.csdn.net/qq_34134078/article/details/51780356 1.单一原则 即:明确类的定义.通俗来讲,让他们只做一件事,而不是多件事. 提高类的可读性,更加好维护,降低耦合度.当然,方法,变量亦是如此. 2.里氏替换原则 a.子类可以实现父类的抽象方法,但不能覆盖父 类的非抽象方法. b.子类可以增加自己特有的方法. 不遵循的后果:写代码的问题几率大大增大. 3.依赖倒置原则 高层模块不应依赖底层模块,二者应该都依赖抽象.细节依赖抽象

提高 代码 可读性的 一点小建议

3. UI工厂类 与 代码块 UI工厂类: 其实代码很简单,就是把对Label, Button等控件的属性赋值封装一下, 做到一行代码就能创建一个VIew, 如下图, 虽然这一句代码有点长, 但是习惯之后写个View是真心快 UI工厂类.h

提高代码质量:如何编写函数

阅读目录 命名 函数参数 编写函数体 总结 函数是实现程序功能的最基本单位,每一个程序都是由一个个最基本的函数构成的.写好一个函数是提高程序代码质量最关键的一步.本文就函数的编写,从函数命名,代码分布,技巧等方面入手,谈谈如何写好一个可读性高.易维护,易测试的函数. 回到顶部 命名 首先从命名说起,命名是提高可读性的第一步.如何为变量和函数命名一直是开发者心中的痛点之一,对于母语非英语的我们来说,更是难上加难.下面我来说说如何为函数命名的一些想法和感受: 采用统一的命名规则 在谈及如何为函数取一

java技巧--提高代码运行效率

java技巧--提高代码运行效率 1.尽量在合适的场合使用单例 使用单例可以减轻加载的负担,缩短加载的时间,提高加载的效率,但并不是所有地方都适用于单例,简单来说,单例主要适用于以下三个方面 第一,控制资源的使用,通过线程同步来控制资源的并发访问 第二,控制实例的产生,以达到节约资源的目的 第三,控制数据共享,在不建立直接关联的条件下,让多个不相关的进程或线程之间实现通信 - 2.尽量避免随意使用静态变量 要知道,当某个对象被定义为stataic变量所引用,那么gc通常是不会回收这个对象所占有的

javascript 代码可读性

可读性的大部分内容都是和代码缩进相关的,必须保证代码有良好的格式.可读性的另一方面就是注释,一般而言,有如下一些地方需要进行注释 1.1.1           函数和方法 每个函数或方法都应该包含一个注释,描述其目的和用于完成任务所可能使用的算法,陈述事先的假设也非常重要,如参数代表什么,函数是否有返回值等等 1.1.2           大段代码 用于完成单个任务的多行代码应该在前面放一个描述任务的注释 1.1.3           复杂的算法 如果使用了一个独特的方式解决某个问题,则要

如何提高代码质量

一.代码质量 软件是交付给用户,并由用户体验的产品:代码则是对软件正确且详细的描述,所以代码质量关系到软件产品的质量.虽然软件质量不等于代码质量,但是代码上的缺陷会严重的影响到软件产品的质量.因此,为提高代码质量的投入是值得的. 二.软件产品质量通常可以从以下六个方面去衡量 功能性,即软件是否满足了客户业务要求: 可用性,即衡量用户使用软件需要付出多大的努力: 可靠性,即软件是否能够一直处在一个稳定的状态上满足可用性: 高效性,即衡量软件正常运行需要耗费多少物理资源: 可维护性,即衡量对已经完成

编写优秀代码的10个技巧

作为程序员,写代码是需要一种崇高无上的精神来支撑的,写出优秀的代码,更需要你有深厚的底蕴和良好的编码习惯.在介绍写优秀代码的10个技巧之前,我们先来探讨一下什么样的代码才是优秀的代码. 稳定可靠(Robustness) 可维护且简洁(Maintainable and Simple Code) 高效(Fast) 简短(Small) 共享性(Reusable) 可测试性(Testable) 可移植性(Portable) 面对以上的目标,我们总结了以下10个写代码的技巧,希望对你有所帮助. 1.百家之

[转载]编写优秀代码的10个技巧

作为程序员,写代码是需要一种崇高无上的精神来支撑的,写出优秀的代码,更需要你有深厚的底蕴和良好的编码习惯.在介绍写优秀代码的10个技巧之前,我们先来探讨一下什么样的代码才是优秀的代码. 稳定可靠(Robustness) 可维护且简洁(Maintainable and Simple Code) 高效(Fast) 简短(Small) 共享性(Reusable) 可测试性(Testable) 可移植性(Portable) 面对以上的目标,我们总结了以下10个写代码的技巧,希望对你有所帮助. 1.百家之