很多程序员在写代码的时候往往都不注意代码的可读性,让别人在阅读代码时花费更多的时间。其实,只要程序员在写代码的时候,注意为代码加注释,并以合理的格式为代码加注释,这样就方便别人查看代码,也方便自己以后查看了。下面分享十个加注释的技巧:
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个注释技巧 #### 技巧1:逐层注释 逐层注释是指为代码的不同层级提供相应的注释。这种做法有助于增强代码的可读性和可维护性。例如: - **针对每个类**:应该包含类的功能概述、作者信息、...
以下是对提高代码可读性的十大注释技巧的详细解析: 1. **逐层注释**:确保每个代码块都有适当的注释,如类、方法、函数等,包含基本信息、作者、日期及功能描述。使用标准格式,如C#的XML注释或Java的Javadoc,有...
本文主要探讨C++程序中的注释写作技巧,以提升代码的可读性和可维护性。 #### 注释的重要性 注释在程序中扮演着非常重要的角色,它们可以帮助程序员理解代码的逻辑、目的和行为。随着时间的推移,原始作者可能会...
在软件开发中,代码的可读性至关重要。它不仅影响代码的维护性,还关系到团队协作的效率。Python以其简洁明了的语法而闻名,但即便如此,编写易于...记住,代码可读性的提高不仅可以提升开发效率,还可以降低维护成本。
在编程世界中,良好的代码注释是至关重要的,它能够帮助开发者理解代码的功能、用途以及实现方式,提高团队协作效率,降低维护成本。Visual Studio 2013(VS2013)作为一款强大的集成开发环境(IDE),提供了一系列...
代码注释不仅是对程序逻辑的解释,更是提高代码可读性的关键。良好的注释可以帮助新加入项目的成员快速理解代码功能,降低学习曲线,提升团队协作效率。此外,注释还能记录设计决策,便于未来修改或优化时参考。通过...
在编程过程中,良好的注释习惯是至关重要的,它不仅能够提高代码的可读性,也有助于团队协作和后期维护。以下是13个关于C#代码注释的实用技巧: 1. **统一注释风格**:确保在不同级别的代码块(如类、方法等)上...
在C#编程中,良好的注释习惯是提升代码可读性和团队协作效率的关键。这篇文章将深入探讨C#中的注释代码技巧,旨在帮助初学者更好地理解和应用这些技巧。 首先,我们要了解C#中的两种基本注释类型:单行注释和多行...
在Android开发过程中,良好的代码注释是至关重要的。"Android-BeautifulNotes-优美的代码注释...通过学习和实践其中的原则和技巧,我们可以使自己的代码更加优雅,更具可读性,从而提高开发效率和团队合作的默契程度。
然而,编写 Matlab 代码时需要遵守一定的编程规范和技巧,以提高代码的可读性和执行效率。本文总结了 Matlab 编程中的一些实用技巧,包括注释技巧、调试技巧、编辑技巧等。 一、注释技巧 1. 文件命名技巧:m 文件...
《编写可读性代码的艺术》是一本专注于提升代码质量,特别是强调代码可读性的书籍。在IT行业中,尤其是在软件开发领域,代码的可读性至关重要,因为它直接影响到代码的维护和扩展。良好的代码可读性不仅是对其他...
宏定义在代码开发和调试过程中扮演着重要角色,尤其在大型项目中,能够有效地提升效率和代码可读性。本文将深入探讨如何巧用C语言的宏定义来实现自动注释调试代码,帮助开发者更好地理解和应用这一技巧。 首先,...
2. **格式化代码**:保持代码整洁和结构化是提高可读性的关键。每个主要的 Transact-SQL 子句应单独一行,如示例所示,使得语句清晰易读。此外,关键字、函数名和数据类型通常使用大写字母,如 `SELECT`, `FROM`, `...
### 编写可读性代码的艺术 #### 一、引言与背景 在现代软件开发领域,编写高质量、高可读性的代码被视为一种至关...通过学习本书的内容,开发者可以更好地理解代码可读性的重要性,并学会如何有效地提高代码质量。
通过理解和熟练应用这些注释技巧,开发者不仅可以提升个人编程效率,还能增强团队间的沟通,使代码更易于理解和维护。在"JAVA实验对源代码进行注释"的实践中,同学们将有机会亲身体验到注释在软件开发过程中的重要性...
“工具”标签则表明可能涉及的是利用特定的IDE工具来提高开发效率,例如IntelliJ IDEA的快捷键、插件或者设置,这些都是提升代码注释生成效率的有效手段。 至于压缩包中的"intellij-javadocs.xml"文件,这可能是...
Java 开发者应该养成习惯,为代码加注释,以提高代码的可读性和可维护性。 二、不要让事情复杂化 Java 开发者sometimes喜欢对简单的问题想出复杂的解决方案,引入不必要的框架、属性文件、面向对象解决方案、多...
良好的注释能帮助其他开发者快速理解代码的功能和结构,提高代码的可读性和可维护性。在Gitee的“码力传递”活动中,可以看到各种注释的示例,从中我们可以学习如何编写清晰、简洁且具有描述性的注释。 代码运行...
【Java初学者完整代码+注释16】这个资源针对的是正在学习Java编程语言的初学者,提供了21个课程的代码示例和详细的注释,旨在帮助他们扎实地掌握Java的基础知识。在这个系列中,我们可以学到许多重要的编程概念和...
下面将详细阐述 Java 语言的基础知识以及如何通过注释来提高代码可读性。 Java 是一种广泛使用的面向对象的编程语言,由 Sun Microsystems(现为 Oracle 公司)于1995年发布。它的设计目标是“一次编写,到处运行”...