Comentarios en el lenguaje de programación C

Cuando hablamos de comentarios en el lenguaje de programación C, hablamos de una serie de anotaciones que inician con los caracteres /* y terminan con */,  los comentarios en un programa nos sirven para dar explicación de ciertas partes de código que necesariamente requieren de una explicación para un mejor entendimiento de los mismos, cuando digo que necesariamente requieren una explicación me refiero a que la mayoría del código debe de ser fácilmente interpretado por cualquier programador sin necesidad de usar comentarios, los comentarios deben de ser evitados la mayor parte del tiempo dentro del código y debemos usarlos dentro de manera ordenada, legible y correcta.

A continuación se muestra el ejemplo de un comentario:

/* Código comentado aquí */

/* Este es otro ejemplo que nos

 * muestra un párrafo que

 * está comentado.              

 */     

La forma de comentar en C++ y en el estándar C99 haciendo uso de "//"  no debería ser usada en el lenguaje de programación C si se desea portabilidad hacia compiladores anteriores a C99, estos caracteres no son permitidos en compiladores que están basados en el estándar C89/C90 y para efectos de portabilidad darían problemas al momento de compilar el código. Aunque esta forma de comentar sea aceptada por algunos compiladores, no es parte del estándar C89/C90 y si queremos asegurar compatibilidad hacia atrás no debemos de usarlos.

Los comentarios deben de usar únicamente el estilo /* . . . */ como anteriormente se comento, solo si se desea potabilidad hacia compiladores basados en el estándar C89/C90 y también si el estilo de programación adoptado por el programador lo requiere. 

Como regla obligatoria general los comentarios no deben de estar anidados, un comentario debe de comenzar con /* y continuar hasta encontrar un */, pero nunca deben de tener estos caracteres en medio del comentario.

Si por algún motivo se tienen que comentar secciones de código, estas secciones no deben de ser comentadas haciendo uso de los caracteres mencionados anteriormente, para comentar secciones de código debemos de usar las directivas condicionales de compilación (#if . . . #endif).

#if 0

/* Código comentado aquí*/

#endif

Debemos de tener en cuenta que en ciertas secciones de nuestro programa vamos a tener comentarios, por tal motivo no podemos comentar código con (/* ... */), por que estaríamos violando la regla de no tener comentarios anidados.

Es bueno que al momento de hacer comentarios sigamos reglas y cierto estilo al escribir, las siguientes reglas me han ayudado a tener un código de fácil mantenimiento, inteligible y mi propio estilo de programación, estás reglas las he tomado en el transcurso del tiempo y están basadas en algunos estándares ya establecidos y posiblemente les sean de ayuda para algunos de ustedes:

• Nunca usar comentarios anidados.
• Los bloques de comentarios describiendo estructuras, tipos, etc., deben de comenzar con / en la columna 1, * en la columna 2 en cada una de las siguientes líneas del bloque y terminar con */ en las columnas 2 y 3. (el comando grep '^.\*' agarrará todos los bloques de comentarios dentro del archivo). 
• Los comentarios hechos dentro de bloques de código, deben de tener la misma alineación que la de código descrito.
• Para los comentarios de una sola línea, comentarios que usan el carácter //, no compatible con C89/C90, y que se encuentran al final de la línea, siempre use la misma alineación, para que los comentarios estén alineados. 
• Al inicio de cada programa escriba comentarios de lo que hace el programa.
• Para las funciones escribir comentarios con información de que la función hace, la explicación de los parámetros (valores, significado y uso) y valor que regresa
• No contradecir el código con los comentarios, usarlos únicamente para explicar código que podría no ser fácilmente entendido.
• Defina comentarios para las secciones de código en la cual no se hace nada, especificando que ahí no se hace nada.

Resumiendo acerca del uso de comentarios en el lenguaje de programación en C, tenemos lo siguiente:

1. Use los caracteres /* y */, para realizar comentarios de una y varias líneas en C, si se requiere que el código sea compatible con los compiladores anteriores y sea portable entre los compiladores de C, ya que está forma de comentar es usada en todos los compiladores de C.
2. Nunca use comentarios anidados.
3. Use los caracteres // para realizar comentarios de una sola línea. Tenga en cuenta que estos caracteres no serán compatibles con compiladores anteriores a C99. Si se desea fácil portabilidad no use estos caracteres para realizar comentarios.