函数注释应该放到头文件还是C文件？大家可以来讨论下

Jelin

我个人比较喜欢 Doxygen 的代码注释风格，我在Github上浏览一些C项目时发现很多项目都用 Doxygen 注释格式，目前许多代码编辑器或者IDE都支持 Doxygen 的代码注释识别，例如VSCode, CLion...

在注释的规范上我也思考了许多，最让我纠结的就是"函数注释应该放在头文件里还是C文件里"这个问题，我做了如下思考：
        - 如果放在C文件，好处是头文件就比较精简，在函数声明前加一行简单的函数说明，也未尝不可。
        - 如果放在头文件，好处是可以专注写函数的实现，而头文件就可以更加丰富，毕竟头文件是查看功能模块的第一入口。
        - 两者兼得，也可以，在C文件先写下注释，之后再同步一份到头文件，就是比较麻烦，增加一些维护成本

网上有相关的讨论，我觉得比较好的有这种：
        - 头文件写函数的相关信息，例如简介，参数说明，用法等，在函数体（C文件中）写该函数的实现原理，过程，维护信息等

这就又引出来几个问题：
        - 是否每个的函数都需要有注释？
        - 函数注释应该是”先写“还是”之后再写“？
        - 除了 Doxygen 还有没有别的好的代码注释风格？
        - 函数注释有必要吗？
        - 注释的简洁应该如何定义？

你有没有更好的Idea? 欢迎来这里讨论。

eric2013

我觉得写到C文件方便，大部分人都是go to查看原始函数说明和函数源码。

能注释的最好注释，省的以后自己看代码都忘了。

eric2013

我觉得写到C文件方便，大部分人都是go to查看原始函数说明和函数源码。

能注释的最好注释，省的以后自己看代码都忘了。

eric2013

代码注释这块，以各种RTOS为例，我觉得做的最好的还是uCOS-III，注释做的真心好。

挖东衣宇

接触不同的SDK，个人比较喜欢注释放在.h里，这样搜索代码比较方便，不会在.c里重复出现一个或多个同一个函数或者函数参数，且函数和函数之间不会被注释掉间隔开，从而影响代码阅读

庄永

代码需要保密就写在头文件，不需要最好写在C文件。注释风格Doxygen比较推荐，后期生成文件方便。

imliyucai

我正在用 Nordic SDK 。它有些示例程序，我当然是在示例上修修改改变成我自己的程序。
它的函数注释就是在 .h 文件里。而要看函数的作用和用法只能跳到 .c 文件。非常不方便。