软件开发技巧---TODO特殊事项标注 原创

软件开发技巧—TODO特殊事项标注



更多精彩内容
👉个人内容分类汇总 👈
👉开发工具 👈

1、前言

🧘🏻软件开发中的TODO是一种用于标记待办事项或未完成任务的注释方法,它有助于提高代码质量和开发效率。

在软件开发过程中,开发者经常会遇到需要暂时搁置的任务或问题,例如一个功能尚未实现、某个部分需要重构、潜在的bug等。

TODO注释是软件开发中一个重要的辅助工具,它不仅可以帮助个人开发者组织思路和工作,还能在团队中起到沟通和协调的作用。

使用TODO注释可以提高代码的可维护性,确保未解决的问题和待完成的任务不会被遗忘。在实际开发中,养成合理使用TODO注释的习惯是非常有益的

具体作用如下:

  1. 任务追踪:通过在代码中加入TODO注释,开发者可以快速记录和追踪待解决的问题或未完成的功能。
  2. 方便定位:TODO注释可以作为代码中的一个标记,帮助开发者快速定位到相关代码段,尤其是在大型项目中非常有帮助。
  3. 团队协作:在多人协作的项目中,TODO可以帮助团队成员明确谁负责哪个任务,以及任务的优先级,从而提高团队的协作效率。
  4. 代码管理:项目管理者可以利用TODO注释来监控项目进度和问题点,以便更好地控制和管理项目。
  5. 避免中断:写代码时遇到小问题,但又不想打断当前的思路,可以使用TODO注释暂时记录下来,待后续处理。
  6. 区分类型:除了普通的TODO注释,还可以使用FIXME、XXX等不同的标签来区分任务的性质,如BUG修复、代码优化等。
  7. 集成开发环境:许多IDE(如Qt、VS、PyCharm、IntelliJ IDEA)支持TODO注释的识别和提示,使得开发者可以在特定视图中查看所有标记的任务,甚至可以设置过滤器来管理这些任务。

2、环境

  • Windows11
  • Qt 5.14.2
  • Qt Creator 10.0.2
  • VS2017

3、TODO注释规范

TODO注释应使用全大写的"TODO"字符串,并在随后的圆括号内提供相关信息

TODO注释是一种编码实践中常用的技术,用于标记代码中需要未来处理的部分。为了确保这些注释的有效性和可追溯性,遵循一定的规范是非常重要的。以下是一些关于如何正确使用TODO注释的建议:

  • 格式要求:TODO注释应以"TODO"开头,后跟一个空格(如果没有空格很多IDE的识别功能都无法检测到),然后是括号包围的注释内容。这个内容可以包括你的名字、电子邮件地址、bug编号、标注日期或其他与任务相关的标识信息。

  • 注释内容:在括号之后,应该提供一个可选的冒号,后跟一行或多行注释,详细说明需要完成的任务或待解决的问题。如果使用多行注释,第一行之后的注释行应该缩进,以区分常规注释行。

  • 包含截止日期:在注释中包含一个目标完成日期或等待某个事件发生的指示,可以帮助开发者更好地规划和跟踪任务进度。

  • 格式

    1. // TODO (mahuifa):这里需要添加某某功能。/ // TODO (mahuifa 2024-4-28): 这里功能未测试

    2. //TODO: 某某功能。注意这里是使用英文的:,如果是中文的则识别不到。

  • 标注类别:根据IDE内置的类别或者项目组定义的类别不同,常见的类别有TODONOTEFIXMEBUGWARNING等;

    • TODO:待办事项,标记代码中需要完成但尚未实现的功能或任务;

    • NOTE:用于标记一般性的注释或提示信息,通常用于向其他开发者解释某段代码的用途或设计决策,例如下列ffmpeg的注释。

      在这里插入图片描述

    • FIXME:指出代码中需要修正或修复的地方,可能是因为代码有错误或不符合预期的行为;

    • BUG:明确指出代码中存在的bug或错误;

    • WARNING:提醒开发者注意潜在的问题或不建议的做法;

    • DEPRECATED:弃用注释,标记那些已经过时且不建议使用的代码,这通常意味着有一个更好的替代方案存在,或者该代码在未来的版本中可能会被移除。

4、Qt中使用TODO

Qt Creator中有TODO插件,可以快速检测代码中的TODO注释,非常便于使用;

  1. 打开Qt Creator,【帮助】->【关于插件】,勾选【Todo】插件,然后重启软件;

    在这里插入图片描述

  2. 打开【首选项】,选择【To-Do】,这里就是支持的特殊注释标签了,可以选择添加自己使用的标签;

    1. scan the whole active project:显示整个活动工程代码中的特殊注释标签;
    2. scan only the currently edited document:显示当前文件中的特殊注释标签;
    3. scan the current subproject:显示当前子项目中的特殊注释标签。

    在这里插入图片描述

  3. 在代码中随便添加一些注释标签,然后在输出视图栏打开【To-Do事项】,就可以看见代码中的特殊注释了;

    在这里插入图片描述

  4. 注意:在预处理语句#if后使用TODO也无法检测到,例如:

    #if 1   //TODO:1233
    
    #endif
    

5、VS中使用TODO

  1. 打开VS,选择【工具】->【选项】->【任务列表】,就可以看见支持的注释标签了;

    在这里插入图片描述

  2. 在输入栏中输入名称,点击【添加】就可以添加自己的标签了;

    在这里插入图片描述

  3. 打开一个工程,在代码中添加注释标签,然后打开【视图】->【任务列表】,就可以看见代码中的特殊注释了;

    在这里插入图片描述

  4. 需要注意的是在VS2017里这个功能并不完善,上图中1位置的函数注释无法检测到,2位置的过滤功能只有当前文件和所有打开文件有效,如果文件关闭了就检测不到了(后面版本VS可能已经解决了)。

6、总结

使用 TODO 注释是一种良好的编程实践,有助于提高代码质量、可维护性和团队协作效率。

➖➖🟩➖➖➖🟩➖➖
➖➖➖🟩🟩🟩➖➖➖
➖➖🟩⚪🟩⚪🟩➖➖
➖➖🟩🟩🟩🟩🟩➖➖
➖➖➖➖➖➖➖➖➖
🟩➖🟩🟩🟩🟩🟩➖🟩
🟩➖🟩🟩🟩🟩🟩➖🟩
🟩➖🟩🟩🟩🟩🟩➖🟩
🟩➖🟩🟩🟩🟩🟩➖🟩
➖➖🟩🟩🟩🟩🟩➖➖
➖➖➖🟩➖🟩➖➖➖
➖➖➖🟩➖🟩➖➖➖

posted @ 2024-04-29 00:38  mahuifa  阅读(0)  评论(0编辑  收藏  举报  来源