¿Cuál es más práctico para comentar, la declaración (en el archivo de encabezado) o la definición (en el archivo de origen)? Tal vez debería comentar ambos, o comentar ninguno y ponerlo todo en un archivo separado ...¿Debo comentar la declaración o la definición en C++?
Debe documentar completamente el archivo de encabezado con la más alta prioridad.
Los comentarios en la definición se deben concentrar en los detalles de implementación, mientras que los comentarios del encabezado se deben concentrar en la interfaz.
Una tercera fuente de documentación, como usted sugirió, es útil también. Debe describir el concepto general.
Una gran ventaja de los archivos de encabezado de comentario es que puede crear documentación automáticamente si se adhiere a alguna sintaxis simple. ¡Saluda al doxygen!
Depende de lo que diga el comentario y de quién esperas leer.
Quiero añadir a la respuesta de ypnos:
Donde sus comentarios van depende de quién es su audiencia. Pensar que su código es de código cerrado ayuda en este sentido: los encargados del mantenimiento pueden ver la implementación, los clientes/usuarios solo pueden ver la interfaz. Si el comentario es necesario para los usuarios, debe ir en la interfaz. Si el comentario solo es relevante para la implementación dada, probablemente solo necesite entrar en la implementación (pero no necesariamente, dependiendo de su audiencia).
No digo que la respuesta seleccionada sea incorrecta (estoy de acuerdo con ella), pero no tengo idea de cómo alguien puede aceptar una respuesta no empírica cuatro minutos después de haberla formulado. –
Tenía sentido para mí cuando lo leí ... ¿No es ese el objetivo de este sitio? Si no fuera así, el solicitante no podría elegir la respuesta. –
Claro, pero después de 4 minutos, ¿cómo sabe que una respuesta mejor o más perspicaz no aparecerá? Lo encontré extraño, eso es todo. –