`
啸笑天
  • 浏览: 3460081 次
  • 性别: Icon_minigender_1
  • 来自: China
社区版块
存档分类
最新评论

提高代码可读性的十大注释技巧

阅读更多

很多程序员在写代码的时候往往都不注意代码的可读性,让别人在阅读代码时花费更多的时间。其实,只要程序员在写代码的时候,注意为代码加注释,并以合理的格式为代码加注释,这样就方便别人查看代码,也方便自己以后查看了。下面分享十个加注释的技巧:

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个注释技巧

    ### 提高代码可读性的10个注释技巧 #### 技巧1:逐层注释 逐层注释是指为代码的不同层级提供相应的注释。这种做法有助于增强代码的可读性和可维护性。例如: - **针对每个类**:应该包含类的功能概述、作者信息、...

    提高代码可读性的十大注释技巧分享

    以下是对提高代码可读性的十大注释技巧的详细解析: 1. **逐层注释**:确保每个代码块都有适当的注释,如类、方法、函数等,包含基本信息、作者、日期及功能描述。使用标准格式,如C#的XML注释或Java的Javadoc,有...

    养成C++编程好习惯提高程序可读性_之注释篇

    本文主要探讨C++程序中的注释写作技巧,以提升代码的可读性和可维护性。 #### 注释的重要性 注释在程序中扮演着非常重要的角色,它们可以帮助程序员理解代码的逻辑、目的和行为。随着时间的推移,原始作者可能会...

    提升Python代码可读性的艺术:最佳实践与技巧

    在软件开发中,代码的可读性至关重要。它不仅影响代码的维护性,还关系到团队协作的效率。Python以其简洁明了的语法而闻名,但即便如此,编写易于...记住,代码可读性的提高不仅可以提升开发效率,还可以降低维护成本。

    VS2013代码注释

    在编程世界中,良好的代码注释是至关重要的,它能够帮助开发者理解代码的功能、用途以及实现方式,提高团队协作效率,降低维护成本。Visual Studio 2013(VS2013)作为一款强大的集成开发环境(IDE),提供了一系列...

    测试软件-代码注释统计

    代码注释不仅是对程序逻辑的解释,更是提高代码可读性的关键。良好的注释可以帮助新加入项目的成员快速理解代码功能,降低学习曲线,提升团队协作效率。此外,注释还能记录设计决策,便于未来修改或优化时参考。通过...

    C#注释代码的13技巧

    在编程过程中,良好的注释习惯是至关重要的,它不仅能够提高代码的可读性,也有助于团队协作和后期维护。以下是13个关于C#代码注释的实用技巧: 1. **统一注释风格**:确保在不同级别的代码块(如类、方法等)上...

    注释代码技巧 c#中 很详细的文章

    在C#编程中,良好的注释习惯是提升代码可读性和团队协作效率的关键。这篇文章将深入探讨C#中的注释代码技巧,旨在帮助初学者更好地理解和应用这些技巧。 首先,我们要了解C#中的两种基本注释类型:单行注释和多行...

    Android-BeautifulNotes-优美的代码注释

    在Android开发过程中,良好的代码注释是至关重要的。"Android-BeautifulNotes-优美的代码注释...通过学习和实践其中的原则和技巧,我们可以使自己的代码更加优雅,更具可读性,从而提高开发效率和团队合作的默契程度。

    Matlab注释技巧.pdf

    然而,编写 Matlab 代码时需要遵守一定的编程规范和技巧,以提高代码的可读性和执行效率。本文总结了 Matlab 编程中的一些实用技巧,包括注释技巧、调试技巧、编辑技巧等。 一、注释技巧 1. 文件命名技巧:m 文件...

    编写可读性代码的艺术.docx

    《编写可读性代码的艺术》是一本专注于提升代码质量,特别是强调代码可读性的书籍。在IT行业中,尤其是在软件开发领域,代码的可读性至关重要,因为它直接影响到代码的维护和扩展。良好的代码可读性不仅是对其他...

    巧用C语言宏定义实现自动注释调试代码

    宏定义在代码开发和调试过程中扮演着重要角色,尤其在大型项目中,能够有效地提升效率和代码可读性。本文将深入探讨如何巧用C语言的宏定义来实现自动注释调试代码,帮助开发者更好地理解和应用这一技巧。 首先,...

    如何编写可读性好的代码

    2. **格式化代码**:保持代码整洁和结构化是提高可读性的关键。每个主要的 Transact-SQL 子句应单独一行,如示例所示,使得语句清晰易读。此外,关键字、函数名和数据类型通常使用大写字母,如 `SELECT`, `FROM`, `...

    编写可读性代码的艺术.pdf

    ### 编写可读性代码的艺术 #### 一、引言与背景 在现代软件开发领域,编写高质量、高可读性的代码被视为一种至关...通过学习本书的内容,开发者可以更好地理解代码可读性的重要性,并学会如何有效地提高代码质量。

    JAVA实验对源代码进行注释

    通过理解和熟练应用这些注释技巧,开发者不仅可以提升个人编程效率,还能增强团队间的沟通,使代码更易于理解和维护。在"JAVA实验对源代码进行注释"的实践中,同学们将有机会亲身体验到注释在软件开发过程中的重要性...

    idea代码注释生成

    “工具”标签则表明可能涉及的是利用特定的IDE工具来提高开发效率,例如IntelliJ IDEA的快捷键、插件或者设置,这些都是提升代码注释生成效率的有效手段。 至于压缩包中的"intellij-javadocs.xml"文件,这可能是...

    Java开发者的十大戒律.pdf

    Java 开发者应该养成习惯,为代码加注释,以提高代码的可读性和可维护性。 二、不要让事情复杂化 Java 开发者sometimes喜欢对简单的问题想出复杂的解决方案,引入不必要的框架、属性文件、面向对象解决方案、多...

    Gitee 七周年码力传递,代码段/代码故事/代码注释/代码运行结果等等

    良好的注释能帮助其他开发者快速理解代码的功能和结构,提高代码的可读性和可维护性。在Gitee的“码力传递”活动中,可以看到各种注释的示例,从中我们可以学习如何编写清晰、简洁且具有描述性的注释。 代码运行...

    java初学者完整代码+注释16

    【Java初学者完整代码+注释16】这个资源针对的是正在学习Java编程语言的初学者,提供了21个课程的代码示例和详细的注释,旨在帮助他们扎实地掌握Java的基础知识。在这个系列中,我们可以学到许多重要的编程概念和...

    JAVA个人编写代码待全免得注释

    下面将详细阐述 Java 语言的基础知识以及如何通过注释来提高代码可读性。 Java 是一种广泛使用的面向对象的编程语言,由 Sun Microsystems(现为 Oracle 公司)于1995年发布。它的设计目标是“一次编写,到处运行”...

Global site tag (gtag.js) - Google Analytics