C 中的评论部分和评论块

Question

根据 Doxygen 手册，有一些标准可以正确注释用 C 编写的程序。不幸的是，记录程序的方式似乎没有很好地标准化（即 GNU 编码标准）。

如果我同意函数最常见的标头是：

/** 
 * Brief description.
 *
 * @param a first parameter
 * @return if any return value
 * 
 * Detailed description
 **/

不幸的是，当我需要用

/*

...

*/

快速注释一段代码时，这个解决方案非常烦人。这就是为什么我更喜欢使用不与

//

交互的

/*..*/

的原因。那么函数注释头的最可取的写法是什么呢？此外，当今的大多数标准都基于旧版 C89 标准。

我的问题的第二点涉及章节评论。我的代码中经常有不同的部分，我想清楚地分开它们。例如：

/**
 * @file foo.c
 *
 * StackOverflow Example
 **/

/*************************************************************
 * Includes
 ************************************************************/
#include <stdio.h>
...

/*************************************************************
 * Prototypes
 ************************************************************/
void foo();
void bar();
...

是否有任何广泛使用的 C 编程标准，根据研究精确定义如何编写此类分隔符（不那么麻烦，眼睛不那么累，社区最常用，...）？

Answer 1

我认为这取决于偏好和可读性。

例如我喜欢使用以下内容：

/*----------------------
 | Function
 | Author: 
 | Dependencies:
 ----------------------*/


/*----------------------
 |  Section
 -----------------------*/

//Comments in sections 

为了便于阅读，我将其与以下规则结合使用。

• 在节标题/注释之前返回 2 行
• 章节标题/注释后返回 1 行

我发现阻止引用的最简单方法是突出显示代码，然后使用键盘快捷键 Ctrl + Shift + / 注释掉该块。适用于大多数编辑器。

希望有帮助。