C 中的注释部分和注释 block

Question

据Doxygen's manual ，有一些标准可以正确注释用 C 编写的程序。不幸的是，记录程序的方式似乎没有很好地标准化(即 GNU 编码标准)。

如果我同意函数最常见的 header 是:

/** 
 * 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 + / 注释掉该 block 。适用于大多数编辑器。

希望有帮助。