c++ - 氧气，太重而无法维持？

Question

关闭。这个问题是 opinion-based .它目前不接受答案。

---

想要改进这个问题吗？ 更新问题，以便 editing this post 提供事实和引用来回答它.

关闭 4 年前。

Improve this question

我目前开始使用 doxygen 来记录我的源代码。我注意到语法很重，每次修改源代码时，我也需要更改注释，我真的有一种印象，每次修改源代码都要花费太多时间来修改注释。

您有什么技巧可以有效地记录我的源代码吗？

是否存在用于 doxygen 执行以下操作的编辑器(或现有编辑器的插件)？

• 自动跟踪未同步的代码/注释并警告程序员。
• 在每个新项目的源代码(模板)中自动添加 doxygen 注释格式(例如带有参数名称的模板)

PS:我正在做一个 C/C++ 项目。

Answer 1

是你觉得难的 Doxygen 语法吗？还是您现在必须注释所有功能。

如果是前者，可能会有更适合您的编码风格的不同工具。请记住，Doxygen 支持多种评论风格，因此请多多尝试，直到找到您喜欢的风格。

如果是后者，那就坚持下去。作为一种良好的编程习惯，每个面向公众的函数都应该有一个注释标题，说明:

1. 函数的作用
2. 参数
3. 返回码
4. 有关该功能的任何主要警告/限制。

无论您使用哪种文档工具，这都是正确的。

我的大秘诀:避免过多评论的诱惑。描述你需要什么，仅此而已。 Doxygen 为您提供了很多标签，但您不必全部使用它们。

• 您并不总是需要@brief 和详细说明。
• 您无需将函数名称放在注释中。
• 您无需注释函数原型(prototype)和实现。
• 您不需要在每个文件的顶部添加文件名。
• 您不需要在评论中提供版本历史记录。 (您使用的是版本控制工具，对吗？)
• 您不需要“最后修改日期”或类似日期。

至于你的问题: Doxygen 有一些配置选项可以在注释与代码不匹配时触发警告。您可以将其集成到您的构建过程中，并扫描 Doxygen 输出以查找任何警告。这是我发现的在代码与注释中发现偏差的最佳方法。