专栏首页嵌入式程序猿我为什么建议你这样写注释

我为什么建议你这样写注释

1. 摘要

本文档主要用来指导和建议工程师如何写好软件代码的注释,方便使用Doxygen生成文档

2. 准备工作

安装Doxygen软件

正常的代码工程

3. 实施

好的注释习惯,往往会为你节省很多时间,不管是给自己以后阅读代码还是给别人都是一种良好的开发习惯,而按照一定的规则注释,还可以利用工具直接生成文档,方便代码审阅或者联合开发。Doxygen就是开发中广发使用的工具,如果你留意的话,很多的源码包都是使用Doxygen来生成代码文档,如下图就是我使用Doxygen为工程生成的文档中的一个文件展示

而生成这样的文档,注释就要按照Doxygen的规则,注释就要按照类似如下的格式来书写

更多的书写规则可以参考Doxygen的手册文档,https://www.doxygen.nl/manual/index.html

每一章都讲解的很详细,从安装到开始使用,可以说是step by step。

如果你记不住没关系,,可以多翻阅,这些规则都有例子,或者参阅一些源码包的注释,如我们来看一些源码包中的注释风格:

如lwip 协议栈源码包中的就是按照doxygen来注释的,只要运行相应文件就可以生成文档。

可以看到注释风格就是Doxygen 要求的。同样在其他一些常用的源码包里,大部分都是使用了doxygen来生成相应的文档。这样整个项目的结构和接口都会生成一个详细的文档,可以支持不同格式。大大方便了工作汇报,代码审阅评审,以及联合开发的接口沟通。所以大大推荐采用Doxygen的格式来写注释。尤其现在对中文的支持也越来越好了。

本文分享自微信公众号 - 嵌入式程序猿(InterruptISR),作者:小猿

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2021-01-20

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 为什么我不建议你写注释?

    实际上,注释最多也就是一种必须的恶。若编程语言足够有表达力,或者我们擅长于用这些语言来表达意图,就不那么需要注释了,甚至也许根本不需要。 注释...

    用户7386338
  • 为什么我建议你这样实现MySQL分页

    之前分享了关于MySQL分页实现方案的文章《如何优雅地实现分页查询》,有些读者觉得写得太浅显了,今天我们就继续探讨这个话题,当然由于能力有限,这篇文章也未必能够...

    Bug开发工程师
  • 为什么我不建议你用 Select * ?

    应用程序慢如牛,原因多多,可能是网络的原因、可能是系统架构的原因,还有可能是数据库的原因。

    一个优秀的废人
  • 为什么我不建议你用 if-else ?

    程序员想必都经历过这样的场景:刚开始自己写的代码很简洁,逻辑清晰,函数精简,没有一个 if-else,可随着代码逻辑不断完善和业务的瞬息万变:比如需要对入参进行...

    开发者技术前线
  • 我为什么不建议你使用Python3.7.3?

    之前使用Python的环境一直是Python3.7.3的,一直使用的很正常,没有什么毛病,直到最近做一个图片下载器的时候发现了问题。

    云爬虫技术研究笔记
  • 程序员,为什么不建议你写框架

    肉眼品世界导读: 最近又接手一个无数人望而远之的项目,这个项目核心的东西几乎是一个程序员写出来的,产品经理平时也是望洋兴叹,可是,这个程序员却跑路了 读懂中国...

    肉眼品世界
  • 为什么我还是建议你学点Java呢?

    原因是为什么呢?那是因为, 从根本上没了解到,java 可以做什么,不懂Java的便捷与高效。那么什么是项目? 很多项目都是基于需求来呢?需求如何来呢?其实我们...

    DataScience
  • 为什么我建议你只字不差的阅读

    有个公司,由于所在区域 4G 信号覆盖不好,因此办公区 4G 信号时有时无,在确定原因后,公司发了公告,大概内容如下:

    AndroidTraveler
  • 为什么我不建议你使用Java序列化

    如今大部分的后端服务都是基于微服务架构实现的,服务按照业务划分被拆分,实现了服务的解耦,同时也带来了一些新的问题,比如不同业务之间的通信需要通过接口实现调用。两...

    故里

扫码关注云+社区

领取腾讯云代金券