强氧,太重了维持？

Question

我目前正在开始使用doxygen来记录我的源代码.我注意到语法非常繁重,每次我修改源代码时,我还需要更改注释,我真的有这样的印象,即在源代码中为每个更改修改注释时要花太多时间.

您是否有一些技巧可以有效地记录我的源代码？

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

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

PS:我正在开发一个C/C++项目.

Answer 1

你觉得Doxygen语法难吗？或者你现在必须评论所有的功能.

如果它是前者,可能会有一个不同的工具更适合您的编码风格.请记住,Doxygen支持多种评论样式,因此请进行实验,直到找到您喜欢的样式.

如果是后者,那就强硬吧.作为一个很好的编程实践,每个面向公众的函数都应该有一个注释标题,解释:

1. 这个功能是做什么的
2. 参数
3. 返回码
4. 关于该功能的任何重大警告/限制.

无论您使用何种文档工具,都是如此.

我的重要提示:避免过多评论的诱惑.描述你需要什么,而不是更多.Doxygen为您提供了大量标签,但您不必全部使用它们.

• 您并不总是需要@brief和详细说明.
• 您不需要在注释中放置函数名称.
• 您不需要评论函数原型和实现.
• 您不需要每个文件顶部的文件名.
• 您不需要评论中的版本历史记录.(你正在使用版本控制工具,对吧？)
• 您不需要"上次修改日期"或类似内容.

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

Answer 2

您使用评论的方式或您的发展方式存在严重问题.

Doxygen注释用于接口上的外部/内部文档.如果您的界面变化非常快,那么您应该坐下来首先考虑架构布局.

如果您使用doxygen来记录函数的内部流程,那么您应该重新考虑这种方法(即使这样,这些注释也不会改变那么多).当你有一个计算某个值的函数时,注释/// Calculating xy using the abc algorithm肯定是每天都不应该改变的.

Answer 3

我觉得你回复了你的评论,5分钟好好评论一堂课将在3个月的时间里,除了原作者以外的其他人(实际上有时是原作者)需要改变这个课程的时间会少得多要掌握.

我是第二个David提到的文档支持,在重构参数名称的时候,它会在你的docs部分重命名参数.老实说,我不确定自己会不会做任何其他事情.

"每次修改源代码时,我都需要更改注释"可能是你的文档太多了.如果对函数的更改要求您以某种方式更改每个调用者(或者如果不实际更改,至少检查以确保它们不依赖于过时行为),则只需更改函数的文档即可您正在引入新呼叫者将依赖的新功能.所以理论上它不应该是一个巨大的开销.小的更改,如函数中的优化和错误修正,通常不需要记录.