Por qué es importante la documentación y por qué debería incluirla en su código

Hay una gran cantidad de acrónimos cuando se trata de desarrollo de software. BESO, SECO, SÓLIDO… y así sucesivamente. Pero, cuando se trata de documentar o comentar su código, no existe un eslogan simple.

¿Porqué es eso?

La documentación debe ser tan importante para un desarrollador como todas las demás facetas del desarrollo.

En este artículo, discutiré por qué documentar su código lo llevará a convertirse en un mejor desarrollador y contribuirá a ser un gran miembro del equipo.

Nadie tiene tiempo para eso

La razón principal por la que el código no está documentado es por el tiempo.

Al desarrollar una función que debe completarse dentro de un cierto período de tiempo, rara vez tenemos un momento para detener todo y concentrarnos en documentar nuestro código.

Además de diseñar y escribir el código en sí, también necesitamos someternos a revisiones de código, pruebas de automatización y agregar pruebas unitarias (por nombrar algunas cosas). La documentación queda prácticamente fuera de la ecuación.

Es el detalle menos pensado lo que puede marcar la mayor diferencia en el futuro.

Independientemente de lo que esté desarrollando, es probable que algún día usted o uno de sus colegas tenga que volver a visitarlo. Cuando llegue ese día, no recordarás tan vívidamente lo que escribiste y por qué.

Y si lo recuerda, puede haber algunos casos extremos o usos específicos que pueden no ser claramente evidentes. La solución obvia es la documentación .

Tomarse ese tiempo extra para escribir una descripción adecuada de lo que trabajó le ahorrará una gran cantidad de tiempo en el futuro.

La próxima vez que alguien quiera entender qué sucede dentro de su código, todo lo que tiene que hacer es señalarle la documentación. Te ahorrará tiempo, ya que no necesitarás explicar las cosas, y les ahorrará tiempo a ellos, ya que no dependerán de ti.

Y después de todo, cuando usted, como desarrollador, necesita comprender algo sobre cierto aspecto de la codificación, ¿qué hace?

? ¿Vas a la documentación?

Buen código no necesita documentación

Sí, lo sé, lo sé ... un código bien escrito, que sea conciso y bien pensado, no necesita estar documentado. Parece una historia .

Si bien puede ser así, no renuncia a la necesidad de documentación, y esta es la razón:

  1. Todos estamos muy familiarizados con la solidez del código que comprende una característica. Al mirar una sección del código, es posible que no quede claro que hay otras secciones que están profundamente vinculadas a ella.
  2. Cada servicio que crea tiene una API única. Escribir cómo usar esa API requiere documentación que se pueda leer fuera del código. No desea inflar la clase en sí con detalles sobre cómo usar la API.
  3. Los compañeros de trabajo que trabajan en diferentes departamentos (que pueden no ser desarrolladores) pueden querer comprender lo que hizo y cómo funciona.
  4. Solo el acto en sí puede hacer que mires de manera diferente el código que escribiste. Explicar lo que hace tu código hará que evalúes su validez y quizás consideres cambiar las cosas si no cumplen con tus expectativas.
  5. Por la posteridad

Cómo escribir buena documentación

Una buena documentación es como un buen bloque de código. Breve, simple y fácil de entender. Aquí hay algunas pautas que puede seguir:

  • Entiende a quién va dirigida la documentación. ¿Es solo para desarrolladores? ¿Existe una audiencia más amplia? Comprender esto le ahorrará tiempo, ya que sabrá de antemano cuánto debe elaborar en sus explicaciones.
  • Escribe un trasfondo breve pero descriptivo que explique los puntos principales de lo que construiste. Esto ayudará a los lectores a comprender el propósito de la función y determinar su relevancia para lo que quieren saber.
  • Enumere y describa las perspectivas principales de su característica, asegurándose de señalar cualquier dependencia que exista con otras características.
  • Asegúrese de que haya una marca de tiempo para informar a los lectores sobre la validez de la documentación. Además, si está utilizando ciertas bibliotecas, asegúrese de incluir también sus versiones.
  • Sea generoso con sus ejemplos de codificación, detallando cómo usar correctamente la función que escribió y muestre los resultados esperados.

Ejemplos

Para comprender mejor cómo se ve la buena documentación, revisaremos algunos ejemplos excelentes: Red de desarrolladores de Mozilla (MDN), Django y Stripe.

En la documentación de MDN, puede ver claramente que cada página comienza con una breve explicación sobre el tema.

Luego, procede a detallar los casos de uso y métodos. Finalmente, muestra qué navegadores son compatibles con la función y proporciona enlaces a material relevante.

La documentación de Django es muy sólida. Independientemente de su nivel de codificación, comienzan con una descripción general y tutoriales.

Luego, revisan cada tema, detallándolo meticulosamente, dando fragmentos de código breves y concisos que demuestran lo que se debe hacer.

Espero haber logrado enfatizar la importancia de la documentación y haberle dado algunos consejos sobre cómo comenzar a documentar su código. Si tiene una idea para un acrónimo de documentación, no dude en hacerlo en los comentarios a continuación.

Tal vez KID - K EEP I t D ocumented?

Si te gustó este artículo, aplaude para que otros también puedan disfrutarlo. ???