很多程序员在写代码的时候往往都不注意代码的可读性,让别人在阅读代码时花费更多的时间。其实,只要程序员在写代码的时候,注意为代码加注释,并以合理的格式为代码加注释,这样就方便别人查看代码,也方便自己以后查看了。下面分享十个加注释的技巧:
1. 逐层注释
为每个代码块添加注释,并在每一层使用统一的注释方法和风格。例如:
- 针对每个类:包括摘要信息、作者信息、以及最近修改日期等;
- 针对每个方法:包括用途、功能、参数和返回值等。
在团队工作中,采用标准化的注释尤为重要。当然,使用注释规范和工具(例如C#里的XML,Java里的Javadoc)可以更好的推动注释工作完成得更好。
2. 使用分段注释
如果有多个代码块,而每个代码块完成一个单一任务,则在每个代码块前添加一个注释来向读者说明这段代码的功能。例子如下:
03 |
foreach (Record record in records) |
05 |
if (rec.checkStatus()==Status.OK)
|
12 |
Context ctx = new ApplicationContext();
|
13 |
ctx.BeginTransaction(); |
3. 在代码行后添加注释
如果多行代码的每行都要添加注释,则在每行代码后添加该行的注释,这将很容易理解。例如:
在分隔代码和注释时,有的开发者使用tab键,而另一些则使用空格键。然而由于tab键在各编辑器和IDE工具之间的表现不一致,因此最好的方法还是使用空格键。
4. 不要侮辱读者的智慧
避免以下显而易见的注释:写这些无用的注释会浪费你的时间,并将转移读者对该代码细节的理解。
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)
|
注释标签切忌不要用于解释代码,它只是引起注意或传递信息。如果你使用这个技巧,记得追踪并确认这些信息所表示的是什么。
9. 在代码时添加注释
在写代码时就添加注释,这时在你脑海里的是清晰完整的思路。如果在代码最后再添加同样注释,它将多花费你一倍的时间。而“我没有时间写注释”,“我很忙”和“项目已经延期了”这都是不愿写注释而找的借口。一些开发者觉得应该write comments before code,用于理清头绪。例如:
1 |
public void ProcessOrder()
|
10. 为自己注释代码
当注释代码时,要考虑到不仅将来维护你代码的开发人员要看,而且你自己也可能要看。用Phil Haack大师的话来说就是:“一旦一行代码显示屏幕上,你也就成了这段代码的维护者”。因此,对于我们写得好(差)的注释而言,我们将是第一个受益者(受害者)。
分享到:
相关推荐
### 提高代码可读性的10个注释技巧 #### 技巧1:逐层注释 逐层注释是指为代码的不同层级提供相应的注释。这种做法有助于增强代码的可读性和可维护性。例如: - **针对每个类**:应该包含类的功能概述、作者信息、...
在编程中,注释是必不可少的一部分,它用于解释代码的功能和逻辑,便于其他开发者阅读和理解。C语言风格的注释通常使用`//`单行注释或`/* ... */`多行注释。Source Insight的宏功能允许用户自定义快捷键来执行这些...
以下是对提高代码可读性的十大注释技巧的详细解析: 1. **逐层注释**:确保每个代码块都有适当的注释,如类、方法、函数等,包含基本信息、作者、日期及功能描述。使用标准格式,如C#的XML注释或Java的Javadoc,有...
【小米便签源代码+注释】是一款专为学习Java编程和理解软件开发流程的开发者提供的资源。这个压缩包包含了小米便签应用的完整源代码,并且每段代码都有详细的注释,使得初学者能够更好地理解和学习代码的实现逻辑。 ...
在编程世界中,源代码注释是极其重要的,它们提供了对程序逻辑的解释,帮助开发者理解和维护代码。然而,在某些特定情况下,如编译优化、代码混淆或仅需执行无注释版本时,可能需要去除源代码中的注释。本文将深入...
4. **集成到开发流程**:为了持续监控代码质量,你可以将`linecount`与持续集成(CI)工具结合,如Jenkins、GitLab CI/CD等,每次提交代码时自动运行注释率检查,确保注释的完整性。 5. **优化注释策略**:高注释率...
7. **保持风格一致**:无论注释面向的是非程序员还是其他开发者,注释风格应保持一致,这样阅读者能更容易理解。 8. **内部标签注释**:在团队协作中,使用如“TODO”等特定标签来标记需要进一步处理的代码片段,...
一个健康的注释比例可以帮助保持代码的平衡,确保团队成员可以高效地阅读和理解代码。 此外,该工具可能还会关注注释的位置和结构。例如,函数或类的定义上方应有描述其功能和参数的注释,复杂的逻辑块之前应有概述...
在C#编程中,良好的注释习惯是提升代码可读性和团队协作效率的关键。这篇文章将深入探讨C#中的注释代码技巧,...在阅读提供的"注释代码技巧.doc"文档时,你会找到更多具体实例和详细解释,帮助你更好地掌握这些技巧。
Eclipse是一款广泛使用的Java...尤其在团队协作项目中,标准化的注释有助于其他团队成员理解你的代码,减少沟通成本,提升整体开发效率。因此,熟悉并掌握Eclipse的代码注释模板配置是每个Java开发者必备的技能之一。
代码 辅助 注释 代码 辅助 注释代码 辅助 注释代码 辅助 注释代码 辅助 注释
在团队合作中,良好的代码注释能够帮助其他开发者更快地理解代码的功能和逻辑,节省了阅读和调试的时间。本资源包含一个“java代码注释模板”以及可能的格式化工具,确保了代码注释的一致性和规范性。 Java代码注释...
Java代码注释是编程实践中非常重要的一个环节,它有助于提高代码的可读性和维护性。注释能够解释代码的功能、用途以及实现逻辑,使得其他开发者能更快地理解代码,尤其在团队协作中更是不可或缺。本资源"Java代码...
在编程世界中,良好的代码注释是至关重要的,它能够帮助开发者理解代码的功能、用途以及实现方式,提高团队协作效率,降低维护成本。Visual Studio 2013(VS2013)作为一款强大的集成开发环境(IDE),提供了一系列...
聪哥创作的一款批量保留路径清理代码注释的工具,目前兼容大部分常见的代码注释,涵盖c、java、python、php、js、html、css、mysql、node、vue、ruby等常见编程项目的注释无损清理。 2023年8月19日更新日志: 1.对...
例如,你可以选择一段代码,然后使用快捷键或菜单选项将其转换为注释或取消注释。 2. 版本控制工具: Git等版本控制工具在合并代码时,有时会遇到冲突,这时可以使用其内置的命令或第三方工具来帮助解决,这些工具...
在IT行业中,代码注释和图形工具是程序员和开发者日常工作中不可或缺的部分。这些工具帮助他们更好地理解代码逻辑,提升团队协作效率,同时增加代码的可读性和可维护性。本篇将详细介绍“代码注释图形工具(字符画...
VB代码注释器是一款专为Visual Basic (VB)开发者设计的实用工具,旨在提升编程效率,简化代码注释和取消注释的操作。该插件在安装后,会在VB的集成开发环境(IDE)中添加新的功能按钮,允许用户快速地对代码进行注释...
写这种无用的注释不但浪费你的时间,而且读者在读这种很容易理解的代码时,很容易被你的注释转移注意力,浪费了时间。 5. Be polite(要有礼貌) 不要写不礼貌的注释代码,例如“注意,愚蠢的使用者输入了一个负数...
程序员佛祖代码注释,佛祖保佑,代码无BUG