`
web001
  • 浏览: 99145 次
  • 性别: Icon_minigender_1
  • 来自: 天津
社区版块
存档分类
最新评论

十大注释技巧教你如何书写容易阅读的代码

    博客分类:
  • Java
 
阅读更多

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

1. 逐层注释

为每个代码块添加注释,并在每一层使用统一的注释方法和风格。例如:

  • 针对每个类:包括摘要信息、作者信息、以及最近修改日期等;
  • 针对每个方法:包括用途、功能、参数和返回值等。

在团队工作中,采用标准化的注释尤为重要。当然,使用注释规范和工具(例如C#里的XML,Java里的Javadoc)可以更好的推动注释工作完成得更好。

 

2. 使用分段注释

如果有多个代码块,而每个代码块完成一个单一任务,则在每个代码块前添加一个注释来向读者说明这段代码的功能。例子如下:

01 // Check that all data records
02 // are correct
03 foreach (Record record in records)
04 {
05  if (rec.checkStatus()==Status.OK)
06  {
07  . . .
08  }
09 }
10 // Now we begin to perform
11 // transactions
12 Context ctx = new ApplicationContext();
13 ctx.BeginTransaction();
14 . . .

3. 在代码行后添加注释

如果多行代码的每行都要添加注释,则在每行代码后添加该行的注释,这将很容易理解。例如:

1 const MAX_ITEMS = 10// maximum number of packets
2 const MASK = 0x1F// mask bit TCP

在分隔代码和注释时,有的开发者使用tab键,而另一些则使用空格键。然而由于tab键在各编辑器和IDE工具之间的表现不一致,因此最好的方法还是使用空格键。

 

4. 不要侮辱读者的智慧

避免以下显而易见的注释:写这些无用的注释会浪费你的时间,并将转移读者对该代码细节的理解。

1 if (a == 5// if a equals 5
2 counter = 0// set the counter to zero
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)
2 {
3  // TODO: implement the calculations
4  return 0;
5 }

注释标签切忌不要用于解释代码,它只是引起注意或传递信息。如果你使用这个技巧,记得追踪并确认这些信息所表示的是什么。

 

9. 在代码时添加注释

 

在写代码时就添加注释,这时在你脑海里的是清晰完整的思路。如果在代码最后再添加同样注释,它将多花费你一倍的时间。而“我没有时间写注释”,“我很忙”和“项目已经延期了”这都是不愿写注释而找的借口。一些开发者觉得应该write comments before code,用于理清头绪。例如:

1 public void ProcessOrder()
2 {
3  // Make sure the products are available
4  // Check that the customer is valid
5  // Send the order to the store
6  // Generate bill
7 }

10. 为自己注释代码

当注释代码时,要考虑到不仅将来维护你代码的开发人员要看,而且你自己也可能要看。用Phil Haack大师的话来说就是:“一旦一行代码显示屏幕上,你也就成了这段代码的维护者”。因此,对于我们写得好(差)的注释而言,我们将是第一个受益者(受害者)。

1
5
分享到:
评论

相关推荐

    提高代码可读性的10个注释技巧

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

    sourceinsight 代码行注释,去注释代码插件

    在编程中,注释是必不可少的一部分,它用于解释代码的功能和逻辑,便于其他开发者阅读和理解。C语言风格的注释通常使用`//`单行注释或`/* ... */`多行注释。Source Insight的宏功能允许用户自定义快捷键来执行这些...

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

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

    小米便签源代码+注释

    【小米便签源代码+注释】是一款专为学习Java编程和理解软件开发流程的开发者提供的资源。这个压缩包包含了小米便签应用的完整源代码,并且每段代码都有详细的注释,使得初学者能够更好地理解和学习代码的实现逻辑。 ...

    去除源代码注释

    在编程世界中,源代码注释是极其重要的,它们提供了对程序逻辑的解释,帮助开发者理解和维护代码。然而,在某些特定情况下,如编译优化、代码混淆或仅需执行无注释版本时,可能需要去除源代码中的注释。本文将深入...

    代码注释率统计工具下载

    4. **集成到开发流程**:为了持续监控代码质量,你可以将`linecount`与持续集成(CI)工具结合,如Jenkins、GitLab CI/CD等,每次提交代码时自动运行注释率检查,确保注释的完整性。 5. **优化注释策略**:高注释率...

    C#注释代码的13技巧

    7. **保持风格一致**:无论注释面向的是非程序员还是其他开发者,注释风格应保持一致,这样阅读者能更容易理解。 8. **内部标签注释**:在团队协作中,使用如“TODO”等特定标签来标记需要进一步处理的代码片段,...

    代码注释检测工具,用于进行代码注释统计

    一个健康的注释比例可以帮助保持代码的平衡,确保团队成员可以高效地阅读和理解代码。 此外,该工具可能还会关注注释的位置和结构。例如,函数或类的定义上方应有描述其功能和参数的注释,复杂的逻辑块之前应有概述...

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

    在C#编程中,良好的注释习惯是提升代码可读性和团队协作效率的关键。这篇文章将深入探讨C#中的注释代码技巧,...在阅读提供的"注释代码技巧.doc"文档时,你会找到更多具体实例和详细解释,帮助你更好地掌握这些技巧。

    Eclipse 代码注释模板

    Eclipse是一款广泛使用的Java...尤其在团队协作项目中,标准化的注释有助于其他团队成员理解你的代码,减少沟通成本,提升整体开发效率。因此,熟悉并掌握Eclipse的代码注释模板配置是每个Java开发者必备的技能之一。

    代码 辅助 注释

    代码 辅助 注释 代码 辅助 注释代码 辅助 注释代码 辅助 注释代码 辅助 注释

    java代码注释模板

    在团队合作中,良好的代码注释能够帮助其他开发者更快地理解代码的功能和逻辑,节省了阅读和调试的时间。本资源包含一个“java代码注释模板”以及可能的格式化工具,确保了代码注释的一致性和规范性。 Java代码注释...

    Java代码注释率检查器.rar

    Java代码注释是编程实践中非常重要的一个环节,它有助于提高代码的可读性和维护性。注释能够解释代码的功能、用途以及实现逻辑,使得其他开发者能更快地理解代码,尤其在团队协作中更是不可或缺。本资源"Java代码...

    VS2013代码注释

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

    自主研发的批量保留路径清理代码注释工具

    聪哥创作的一款批量保留路径清理代码注释的工具,目前兼容大部分常见的代码注释,涵盖c、java、python、php、js、html、css、mysql、node、vue、ruby等常见编程项目的注释无损清理。 2023年8月19日更新日志: 1.对...

    程序员佛祖代码注释.txt

    程序员佛祖代码注释,佛祖保佑,代码无BUG

    代码注释图形工具(字符画生成工具)

    在IT行业中,代码注释和图形工具是程序员和开发者日常工作中不可或缺的部分。这些工具帮助他们更好地理解代码逻辑,提升团队协作效率,同时增加代码的可读性和可维护性。本篇将详细介绍“代码注释图形工具(字符画...

    VB代码注释器

    VB代码注释器是一款专为Visual Basic (VB)开发者设计的实用工具,旨在提升编程效率,简化代码注释和取消注释的操作。该插件在安装后,会在VB的集成开发环境(IDE)中添加新的功能按钮,允许用户快速地对代码进行注释...

    注释代码的13条注意事项

    写这种无用的注释不但浪费你的时间,而且读者在读这种很容易理解的代码时,很容易被你的注释转移注意力,浪费了时间。 5. Be polite(要有礼貌) 不要写不礼貌的注释代码,例如“注意,愚蠢的使用者输入了一个负数...

    C/C++/Java 源代码注释清除工具

    标题中的"C/C++/Java 源代码注释清除工具"是一个专门针对这三种编程语言设计的实用程序,它的主要功能是移除源代码文件中的注释。在软件开发过程中,注释对于理解和维护代码至关重要,但在特定情况下,如代码混淆、...

Global site tag (gtag.js) - Google Analytics