软件开发技巧---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内置的类别或者项目组定义的类别不同，常见的类别有TODO、NOTE、FIXME、BUG、WARNING等；

  • 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 注释是一种良好的编程实践，有助于提高代码质量、可维护性和团队协作效率。

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