Comentando código C, encabezado y archivos fuente

Question

Estoy buscando una "mejor práctica" para documentar mi código C. Al igual que en cualquier proyecto, tengo algunos archivos de encabezado ".h" y el archivo de origen respectivo ".c"

En el archivo de encabezado ¿qué tipo de comentario usted pone? Y en los archivos fuente? La pregunta surge porque desde que comenté bien mis archivos de cabecera, los archivos c parecen un desastre.

¿Cuáles son sus mejores prácticas para mantener el código bien comentado?

Answer 1

El encabezado está destinado a usuarios del código. Así que allí documenté la interfaz : cómo usarla, precondiciones y postcondiciones, etcétera.

El archivo .c es para mantenedores. Allí, documentamos la implementación : cómo funcionan las cosas internamente, y por qué funcionan de esa manera.

Answer 2

Si se trata de un proyecto personal, sugeriría que hay muchos coding standards por ahí que podría adoptar (casi todos incluyen secciones sobre cómo diseñar comentarios).

Si no, me imagino que su empresa/equipo/proyecto ya tiene algo en su lugar, así que úselo.

Answer 3

Sugiero adoptar las convenciones impuestas por una herramienta como Doxygen. Luego, en lugar de solo comentarios del código, también puede generar documentación HTML/PDF/Latex, etc. y le da buenas convenciones.

De acuerdo con Thomas acerca de los archivos cpp

Answer 4

Para archivos de origen que sugiero crear una plantilla comentario para Archivo de encabezado y cabecera de la función.

En el caso de los comentarios de encabezado de archivo, debe tener una breve descripción del archivo, nombres de funciones, autor, fecha de creación e historial para registrar las modificaciones.

En caso de encabezado de función, puede explicar la lógica y el propósito de la función y diversos parámetros. Asegúrese de que cualquier lógica compleja o desviación del comportamiento común esté bien documentada mediante comentarios.