La Mejor Forma de Agregar Documentación a tu Código

He aquí una guía rápida sobre como agregar efectivamente documentación a tu código.

Documentación Antes de tus Métodos

Es sabio tener siempre un comentario antes de tus métodos que den una rápida explicación del uso del mismo. El comentario debe explicar el uso exacto del método en términos simples sin entrar en detalles de implementación. Los comentarios deben incluir:

• Los parámetros y los límites de esos parámetros.
• El valor de retorno, si hay limites en este resultado y cualquier valor de error que pueda ser retornado.
• Cualquier excepción que este método pueda lanzar y, quizás, la razón por la que la excepción podría ser lanzada.

 Si escribimos código en Java, estos comentarios pueden ser incluidos en HTML dentro del bloque de documentación JavaDoc, para generar una documentación detallada del API.

Documentación Durante tus Métodos

 

Si haz hecho lo anterior, entonces ya tienes un poco de documentación que hará la vida mas fácil a otros cuando usen tus métodos. Ahora queremos un método que sea fácil de mantener. Por esta razón, debemos agregar comentarios más específicos dentro del mismo. Estos comentarios deben tener uno de los siguientes propósitos:

• Deben describir el uso de una variable o grupo de variables definida.
• Debe dividir el método en diferentes secciones, de modo que cada parte tiene su función explicada. Estos comentarios deberían explicar el código en general.
• Secciones complejas o demasiado técnicas deberían tener comentarios adicionales explicando la sección en un detalle mayor, de modo que puede ser leído más claramente.

Idealmente, estos comentarios dentro del método deberían ser entendibles por alguien nuevo al código, incluso si es para ti mismo si debes dejar ese código por un buen tiempo y en algún momento regresar a hacerle modificaciones.

Documentación Después de tus Métodos

 

Ya deberías tener un método bien documentado, haciéndolo más fácil de entender. Ahora debes realizar una práctica muy recomendada: Dar tu código a alguien mas. La pregunta es ¿Qué tan efectiva será la documentación para alguien que no ha escrito el código?

Debes encontrar a alguien más que quiera darle una mirada a tu código e intentar entenderlo. Analizando:

• Si entienden el código en la primera lectura del comentario, entonces no debería cambiarse.
• Si entienden el código después de leer el comentario muchas veces, deberías intentar elegir otras palabras al comentario para que sea mas claro.
• Si no pueden entender el comentario y el código, significa que se necesita aclarar reescribiendo el comentario.

Después de eso, deberías tener un código mucho mas fácil de entender para gente de todos los niveles, desde aquellos que solamente están haciendo llamadas a tu librería, hasta aquellos otros que modificarán tu software o lo desarrollarán mas adelante.

Cuéntanos tu experiencia en los comentarios si has encontrado otras formas de crear documentación fácil de entender.