CODEWITHSUNDEEP
ccomments
nowox
nowox

Reputation: 29096

Comments section and comment blocks in C

Accordingly to Doxygen's manual, there are some standards to correctly comment a program written in C. Unfortunately the way of documenting a program doesn't seem to be well standardized (i.e. GNU Coding Standards).

If I agree that the most common header for a function is:

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

Unfortunately this solution is quite tiresome when I need to quickly comment a block of code with /* ... */. It is the reason why I prefer using // which doesn't interact with /*..*/. So what is the most advisable way of writing function comment header? Also most of the today's standards are based on a legacy C89 standards.

Second point of my question concerns the section comments. I often have in different sections in my code that I would like to clearly separate. For example: 

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

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

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

Is there any C programming standard largely used that precisely define how to write such separators based on a study (less cumbersome, less tiring for the eyes, most used by the community, ...)?

Upvotes: 1

Views: 11386

Answers (1)

Paul
Paul

Reputation: 185

I think it comes down to preference and readability.

For example I like to use the following:

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


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

//Comments in sections

I use this in conjunction with the following rules for readability.

  • 2 line returns before a section heading/Comment
  • 1 line return after a section heading/Comment

The easiest way I have found to block quote is to highlight the code and then to use the keyboard short-cut Ctrl + Shift + / to comment out that block. Works in most editors.

Hope that helps.

Upvotes: 3

Related Questions