Comentarios / Estilos de documentación en código

Esta podría ser una pregunta estúpida, pero ha estado en mi cabeza por un tiempo y no puedo encontrar una respuesta decente en ningún otro lado.

Tengo un maestro que dice que deberíamos enumerar explícitamente cada parámetro con una descripción, incluso si solo hay uno. Esto lleva a mucha repetición:

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

Al escribir documentación en código, ¿qué tan detallado es?

Para empezar, estoy de acuerdo en que la línea "Función:" en su ejemplo es completamente redundante. También ha sido mi experiencia que la gente enseñó en la escuela a agregar ese tipo de comentario y continuar agregando ese tipo de comentario en su código de producción.

Los buenos comentarios no repiten lo que hay en el código. Responden la pregunta "¿Por qué?" en lugar de "¿Qué?" ¿o como?" Cubren las expectativas sobre las entradas, así como sobre cómo se comportará el código bajo ciertas condiciones. Cubren qué algoritmo X fue elegido en lugar del algoritmo de Y. En resumen, exactamente las cosas que no serían evidentes para alguien más ¹ de la lectura del código.

^{1: Alguien más que esté familiarizado con el idioma en el que está escrito el código. No escriba comentarios para enseñar, comentarios para complementar la información.}

Varios idiomas tienen características de generación de documentos API como Ruby, Java, C # y C ++ (a través de una herramienta de línea de comandos). Cuando lo piensas de esa manera, hace que escribir los documentos de la API sea mucho más importante. Después de todo, responde a la pregunta "¿cómo hago ...?" Por lo tanto, no haré nada repetitivo, como Function: MyFunctioncuando el nombre de la función está claro para que todos lo vean. Las herramientas de generación de documentos de API son lo suficientemente inteligentes como para hacer eso por mí. Sin embargo, los siguientes detalles son útiles, particularmente en métodos / funciones públicas:

• Resumen (qué hace y, cuando sea relevante, un resumen de cómo usarlo)
• Lista de parámetros y lo que se espera.
• Cuál será el valor de retorno (salida)
• Cualquier excepción que pueda ser lanzada explícitamente y por qué

Estos pueden convertirse en herramientas de referencia útiles cuando intenta depurar código. Muchos IDE también usarán los documentos de la API en la información sobre herramientas cuando pases el mouse sobre el nombre de la función.

Si es un lenguaje sin esas características, los comentarios ayudan, pero no tanto.

Si se trata de un método de API pública, sí, debe proporcionar documentación detallada, especialmente sobre los parámetros y el comportamiento esperado. Muchas personas sienten que esto puede ser relajado para métodos / funciones privadas, YMMV.

En general, prefiero escribir código limpio (pequeños métodos / funciones que hacen una cosa y una cosa bien) con nombres de variables sensibles. Esto hace que gran parte de su código se auto documente. Sin embargo, ciertamente siempre documento los casos límite, usos de concurrencia y algoritmos complejos.

En resumen, piensa en ti mismo como un poco peor para usar a las 3 de la mañana dentro de 3 meses a partir de ahora. Te agradecerás por tus increíbles documentos públicos en lugar de descubrir qué significa el parámetro (bandera booleana) ...

Eso es similar a cómo la mayoría de los frameworks -Doc analizan la documentación en código (JavaDoc, PHPDoc, etc.).

Desde Java, autogenerado por IDE:

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

Este es el mismo formato utilizado para generar la Documentación para las características del lenguaje incorporado - Ejemplo: http://download.oracle.com/javase/6/docs/api/java/lang/String.html

Este formato es bastante útil porque muestra claramente a cualquier usuario externo cómo interactuar con su código. Si sus funciones son métodos privados que solo se usan internamente, entonces puede ser un poco inútil, pero supongo que su maestro está tratando de llevarlo a una buena práctica hasta que todos tengan experiencia en hacer esa distinción.

Lo único que a menudo encuentro algo redundante es la descripción de retorno: por lo general, es casi idéntica a la descripción de mi método.

Hay dos propósitos para los comentarios:

1. Sirven para recordarle rápidamente lo que hace su código cuando regresa a él meses / años después. De esta manera, no tiene que volver a leer y analizar su código para actualizar su memoria.
2. Transmiten a otras personas que pueden estar leyendo o trabajando con su código lo que está haciendo su código.

Por supuesto, hay MUCHAS maneras diferentes de abordar esto, pero cuanto más minucioso y consistente sea, mejor. Los comentarios efectivos requieren tiempo para aprender, al igual que la programación efectiva. Tenga en cuenta que es difícil ver el punto de los comentarios en la escuela, ya que nada en lo que esté trabajando es lo suficientemente grande como para justificarlo realmente, pero solo están tratando de presentarlo. Y, por lo general, la forma en que te enseñan a hacerlo es el estilo de tu profesor, no ningún tipo de estándar de ninguna manera. Desarrolla lo que funciona para ti. Y recuerda ... ¡hay un comentario estúpido! :) Ejemplo:

a += 1; //adds 1 to the value in a

De Verdad? ¡Gracias! Jajaja

Me gusta la documentación del sitio web de PHP, así que uso algo similar para mis comentarios en línea y uso de la sintaxis PHPDoc. Vea el ejemplo a continuación.

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

Y como dijo @Larry Coleman, los comentarios en línea deberían decir por qué hiciste algún código.

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

Si está al servicio de la generación de documentos, entonces los comentarios detallados (aunque irritantes) probablemente sean algo bueno. Aunque debe ser un objetivo del equipo mantenerse al tanto de los comentarios y mantenerlos actualizados.

Si es solo el estilo de comentario, tendría problemas con él. Los comentarios excesivos pueden dañar el código tanto como la ayuda. No puedo contar la cantidad de veces que he encontrado comentarios en el código que estaban desactualizados y, como resultado, eran engañosos. Por lo general, ignoro los comentarios ahora y me concentro en leer el código y las pruebas del código para comprender lo que hace y cuál es la intención.

Prefiero tener un código claro, sin comentarios y conciso . Dame algunas pruebas con afirmaciones o métodos descriptivos y estoy feliz e informado.