Documentación del código: ¿Público versus no público?

Soy uno de esos desarrolladores que tiene la mentalidad de que el código escrito debe explicarse por sí mismo y leerse como un libro.

SIN EMBARGO, cuando desarrollo código de biblioteca para que otras personas lo usen, trato de poner tanta documentación en los archivos de encabezado como sea posible; lo que plantea la pregunta: ¿Vale la pena el tiempo para documentar métodos que no son públicos? No los usarán directamente, de hecho, no pueden. Al mismo tiempo, si distribuyo el código sin formato (aunque de mala gana), esos métodos no públicos serán visibles y pueden necesitar explicaciones.

Simplemente buscando algunos estándares y prácticas que todos vean o usen en sus viajes.

Nunca consideraría omitir documentación para componentes internos solo porque un "usuario final" no los usará; el mantenimiento del código es una razón más que suficiente para incluir comentarios de documentación para todos los componentes, de hecho, especialmente para los componentes internos que tienden a ser la parte más compleja (y que suele cambiar).

Dicho esto, puede haber un caso válido para mantenerlos restringidos al código fuente sin encabezado (en lugar de documentarse públicamente), para mantener la abstracción.

Todo esto es bastante subjetivo, eso sí.

Ok, agrego mi forma de comentar / documentar también a la imagen para variar. La razón es que evito describir funciones o funciones miembro que solo se declaran allí en el encabezado. Por un lado, temo agregar demasiado ruido al encabezado. Por otro lado, la documentación junto con la definición es más fácil de hacer coincidir para el mantenedor. A Doxygen no le importa de ninguna manera y puede filtrar los elementos privados si es necesario.

En encabezado de clase:

• encabezados incluidos (por qué)
• definiciones de clase siempre (propósito y responsabilidades)
• las funciones virtuales puras siempre (contrato completo)
• las funciones en línea a menos que los explicadores se expliquen por sí mismos
• otros tipos declarados a menos que se explique por sí mismo
• miembros de datos estáticos (por qué)
• otros miembros de datos a menos que se explique por sí mismo
• las macros si las hay (contrato y por qué)

Código de implementación en clase:

• declaraciones locales de la misma manera que en el encabezado
• definiciones de funciones siempre (contrato completo)
• definiciones de funciones miembro siempre (contrato completo o referencia a la raíz de la anulación virtual)
• variables estáticas definidas si hay alguna (propósito por qué)

En el encabezado de la plantilla:

• lo anterior se fusionó y
• tipos adecuados / no adecuados para argumentos de plantilla y
• qué tan bien se detecta la idoneidad estática

Al private:comienzo de la sección privada se encuentra toda la documentación que los usuarios deberían necesitar.

La documentación vale cualquier día, ayuda a explicar casos de uso e historias de una manera breve. La cantidad de código que se explica por sí mismo no puede explicar el negocio tan fácilmente como pocas líneas de narración de historias. El código definitivamente requeriría que el usuario siga la lógica además de comprender lo que está sucediendo. :-) Mis 2 centavos ...

¡Seguro!

Ese código debe autodocumentarse es un eslogan para vivir. Sin embargo, iría tan lejos como para decir que el código privado necesita tanta documentación, si no más, que el código público, porque generalmente es aquí donde ocurren la mayoría de las suposiciones, solo porque el codificador asume que permanecerá en la oscuridad . Entonces, un par de meses después, cuando se presente un error, pasarás tiempo tratando de recordar cuál fue la idea detrás del código (tal vez tú mismo) escribió.

La documentación no debería estar allí como un buen regalo para los demás. La documentación, en todas sus caras (nombres de variables bien seleccionados, nombres de clase autodocumentados, código bien organizado, métodos correctamente segmentados, etc.) es un regalo para todos los que puedan entrar en contacto con su código, incluido usted mismo.