Mejores prácticas: ¿Dónde deberían funcionar los comentarios en el código C/C++?

Question

Entonces ... Entiendo que esto podría ser subjetivo, pero me gustaría algunas opiniones sobre cuál es la mejor práctica para esto.

Decir que tengo el siguiente encabezamiento y .cpp archivo:

cabecera:

// foo.h 

class foo 
{ 
public: 
    int bar(int in); 
}; 

CPP:

// foo.cpp 

int foo::bar(int in) 
{ 
    // some algorithm here which modifies in and returns the modified value 
} 

Ahora dicen que tengo este comentario función:

/* 
    input: an integer as input to algorithm foo 

    output: The result of the algorithm foo on input in 

    remarks: This function solves P = NP 
*/ 

---

sería colocar este comentario función en la cabecera por encima de la declaración de la función o por encima de la definición de función en el archivo CPP mejores prácticas? Gracias SO

Answer 1

puse comentarios que describen lo hace la función en la cabecera y los comentarios que describe cómo lo hace en el archivo CPP.

Answer 2

Tiendo a utilizar el formato de doxygen como comentarios de funciones en el archivo de encabezado, lo que permite a los programadores que buscan más.

/** 
* Fills the handler with GIF information 
* 
* @param filename GIF File name to be loaded 
* @return Inited GIF Handler or NULL for error 
*/ 
pGifHandler gifHandlerLoad(const char* filename); 

/** 
* Removes all data used by the GIF handler 
* 
* @param gifHandler GIF Handler to be destroyed 
* @note This also clears palette and bitmap(s) 
*/ 
void gifHandlerDestroy(pGifHandler gifHandler); 

Los programadores que quiere saber cómo una determinada función hace el trabajo, deben mirar en el archivo .cpp que se ha comentado cómo se logra que es objetivo.

Answer 3

Ponga comentarios de función en el archivo de encabezado. Eso (aparte del manual) es el primer lugar donde los usuarios de su clase buscarán la documentación. No les importa la implementación, solo acerca de la interfaz.

Answer 4

Personalmente prefiero ponerlo por encima de la implementación. También usaría el estilo Doxygen ya que da la misma información pero genera documentación.

En realidad, no importa, especialmente si vas a construir una documentación separada con doxygen. Ve con lo que TÚ prefieres.

Answer 5

Colocar los comentarios en el encabezado es una mejor solución. Esto se debe a:

• Al buscar la documentación sobre una función, el encabezado es el primer lugar para comprobar .
• Es posible que el archivo de origen no esté disponible.
• El archivo de origen contiene mucho más que declaración de función, y los comentarios útiles de pueden ahogarse.

Answer 6

Utilizo Doxygen y uso una breve descripción de una línea en el encabezado y una gran descripción de varias líneas en el archivo de implementación. Creo que esto produce archivos de encabezado más limpios que son más fáciles de entender.

Nota: Si libera este código como biblioteca, es posible que las personas no deseen profundizar en la implementación. Sin embargo, los archivos de encabezado generalmente son un juego limpio. En este caso, pondría documentación detallada en el encabezado.

cabecera:

// foo.h 

class foo 
{ 
public: 
    /**\brief This function solves P = NP */ 
    int bar(int in); 
}; 

CPP:

// foo.cpp 

/** 
\param[in] an integer as input to algorithm foo 

\returns The result of the algorithm foo on input in 
*/ 
int foo::bar(int in) 
{ 
    // some algorithm here which modifies in and returns the modified value 
} 

Answer 7

me gusta usar condiciones PRE/POST. Ninguna de las respuestas mencionadas es incorrecta. ¿Qué es lo que prefiere su empresa? Pero las condiciones PRE y POST le dicen cuáles son las variables entrantes/salientes y cómo se usan. También asegura que está siguiendo algún tipo de directriz sobre cómo va a invocar la función (condiciones previas) y cuáles son las salidas después de esta función (condiciones de publicación).

Answer 8

Propósito en el encabezado, implementación de contrato por encima de la función, por qué está en el cuerpo de la función.

Eso requiere entregar .cpp, o utilizar una herramienta como doxygen para publicar la documentación.

Ventaja durante las dependencias: la mejora de la documentación no afectará las dependencias del encabezado.

De todos modos, elegir un estilo, y ser coherente

Answer 9

En general, los comentarios deben ser tratados de una manera similar al código de separación - interfaz los comentarios relacionados con la PI (como el ejemplo) iría en el encabezado, mientras que los comentarios relacionados con la implementación serían más adecuados para el archivo .cpp.

Si alguien incluyera sus clases en sus propios programas, debería poder obtener suficiente información del archivo de encabezado para saber cómo usar la clase sin tener que entrar en la implementación. Los comentarios de encabezado que excedan de eso probablemente sean innecesarios y solo sirven para desordenar la información útil.

Answer 10

La mejor práctica es cualquiera que sea el estándar para la organización para la que se escribe el código.

Si es sólo para mí: propósito

función y el uso de la cabecera, los detalles de la función de la aplicación.

Answer 11

Como siempre he usado Visual Assist X, y tengo la capacidad de saltar el código muy fácilmente, uso el archivo de encabezado como índice. Es decir, el archivo de encabezado contiene solo los datos relevantes sin comentarios adicionales para no agregar relleno al archivo. Si el lector desea más información sobre la función, puede saltar a la cpp.

Esto, por supuesto, asume que todas las personas que leen su código tendrán el mismo proceso de pensamiento, que es falso. Sin embargo, es bueno tener solo hinchazón en un solo archivo.

Answer 12

Es como preguntar cuáles son las mejores prácticas para ponerse los calcetines. Algunas herramientas tienen una mejor oportunidad de funcionar si pones la declaración y el comentario juntos y eso probablemente tenga más sentido en cuanto a lo que la gente espera. Pero comentar al azar no tiene sentido. Tener cosas de entrada/salida especialmente, a menos que tengas una herramienta que use eso.Cualquier programador puede ver lo que necesita de la declaración, y lo mismo se aplica al idioma en general. Nada es más inútil que comentarios como // este es el constructor.

Trate de mantener el código en sí mismo lo más simple posible con nombres que tengan sentido y una organización general del código y si hay algo extraño, escriba un párrafo real sobre él como // Tuvimos que hacer esto porque algunos La API extraña que usamos requiere ciertas cosas // que causó que otras cosas se rompieran y las llamadas se optimicen algunas veces // así que no saques estas llamadas a métodos o el optimizador optimiza // otras cosas y la todo el programa se detiene

Answer 13

trabajando en orden de importancia:

1. Si es parte de un proyecto existente y hay un estilo de comentario prevaleciente, úselo. La consistencia dentro de una base de código es más importante que la preferencia individual del desarrollador.

2. Si es un proyecto nuevo, use Doxygen o similar para documentar su código. Aunque eso no responde a tu pregunta, ya que puedes usar ambos estilos con ella. Ejecútelo todas las noches para que tenga documentación fuente navegable actualizada.

3. Personalmente, prefiero incluir solo un breve resumen de una línea de funciones en línea y miembros en archivos de encabezado, ya que de lo contrario es más difícil obtener una breve descripción de la funcionalidad de clase al pasar por el archivo de encabezado. Descripciones detalladas que dejo para el archivo .cpp. Algunos usuarios no comento si su propósito es realmente obvio.

También tengo un gran motivo favorito de los comentarios acerca de descanso, en especial de una sola línea:

por ejemplo, Este comentario es un desperdicio de espacio y puede ser que también se borrará:

/** Get the width */ 
double getWidth(); 

Este comentario es útil:

/** Get the width in inches excluding any margin. */ 
double getWidth(); 

Answer 14

Dentro de la función, se puede poner el comentario sobre la misma línea que la llave de apertura .

/* what is this function for, and so on. Stuff the caller needs to know. */ 
foo() 
{  // pre-condition 
} 

Lo he visto como un lugar recomendado para listar las condiciones previas. Intenté eso y lo encontré bastante limitado, porque tiendo a escribir comentarios detallados. Además, la condición previa es algo que la persona que llama debe conocer y no debe perderse dentro del cuerpo de la función.

De lo contrario, siempre trato de poner descripciones generales de la función fuera de él, y explicaciones de por qué está codificado de la forma en que está dentro de la función, junto al código. Por lo general, estoy de acuerdo con el estilo de los promotores de Doxygen.