Documentación de código: La Guía Completa para Principiantes

Está un poco metido en su primer trabajo de programación, y las cosas se están volviendo más fáciles. Al principio, todo el código con el que tuviste que lidiar podría haberte abrumado y confundido, pero estás empezando a entenderlo. ¡Eso es genial! Ahora te estás preguntando cómo llevar el código que escribes al siguiente nivel. Si bien hay muchas cosas que aprender sobre su pila de programación, muchas de las cuales lo convertirán en un mejor programador, hay algunas que le servirán sin importar en qué pila trabaje. Una de ellas es la documentación de código.

Muchos desarrolladores no escriben suficiente documentación, ya sea porque no ven el valor o porque sienten que no tienen tiempo. No necesitas ser uno de esos desarrolladores. Con un poco de tiempo y mucha práctica, puede agregar documentación para su código que haga que leerlo sea un placer para usted y para cualquier otra persona que venga.

La buena documentación Viene en Muchas Formas

Cuando la mayoría de los desarrolladores piensan en documentación de código, piensan en comentarios. Los comentarios pueden ser adiciones valiosas al código, pero no son la única definición de documentación. La documentación es cualquier cosa que escribes además de tu código para ayudar a otra persona a entender cómo funciona. Puede que no lo piense de esta manera, pero un buen ejemplo de documentación de código es un archivo LÉAME. Un buen ejemplo de documentación básica es el Express.archivo js README. Responde a varias preguntas importantes sobre el framework y le indica cómo puede incluirlo en su proyecto, cómo instalarlo y cómo ejecutar pruebas.

Una buena documentación también puede venir en forma de documentación de API. Una vez más, Expreso.js es un gran ejemplo. Esta versión de la documentación es más una biblioteca de referencia para desarrolladores que usan el framework. Encontrará respuestas a preguntas sobre qué hacen las funciones individuales y qué significan los diferentes parámetros de esas funciones. Sin esa documentación de calidad, Express no tendría tantos equipos usándola como lo hacen.

Y, por supuesto, también puede usar comentarios en línea para codificar el documento. Este tipo de comentarios generalmente no se usan para enseñar el código a personas ajenas a tu propio equipo. En cambio, son útiles para explicar lo que está sucediendo en un código en particular a tus compañeros de equipo o a tu yo futuro.

Por qué debe Documentar Su Código

Como se señaló anteriormente, muchos desarrolladores no entienden el propósito de la documentación de código. Argumentarán que un buen código debe documentarse por sí mismo y que no es necesario explicarlo. Estas personas están, en una palabra, equivocadas. La verdad es que una buena documentación es una parte esencial de cualquier base de código. ¿Por qué? Porque la gente no debería necesitar leer todo tu código para entender lo que hace. “Personas” en esa oración anterior puede referirse a cualquier persona, incluido tu yo futuro.

La verdad es que a menudo, las “personas” que necesitarán entender el código después de que se escriba eres tú. Ese poco de lógica que parecía tan inteligente cuando lo escribiste hace seis meses podría ser difícil de entender hoy en día. Si su código está bien documentado, no necesita pasar tiempo tratando de entender lo que hace. Podrá pasar unos segundos mirando la descripción y luego volver a lo que está trabajando en este momento.

Si tienes la suerte de trabajar en código que usan docenas o cientos de desarrolladores, una buena documentación es aún más importante. La vida de tus usuarios mejorará significativamente si dedicas tiempo a escribir buena documentación, y te lo agradecerán. Literalmente!

La clave para recordar es que una buena documentación ahorra más tiempo del que se necesita para escribirla. Puede ser tu tiempo, o el de los miembros del equipo, o incluso de personas que nunca conocerás. A veces, escribir documentación incluso te ayudará a reconocer una parte de tu código que es demasiado complicada para que puedas simplificarla.

Algunos errores comunes de documentación

Como desarrollador junior, tendrá que dedicar tiempo a aprender qué hace que la documentación sea efectiva. La buena noticia es que puedes aprender de las personas que te precedieron para evitar errores comunes.

Documentación insuficiente

Un error común que veo con la documentación de código es documentar información que ya está claramente visible. Por ejemplo, los desarrolladores perezosos agregarán “documentación” a una función agregando un bloque que proporcione el nombre de una función, así como los nombres de cada parámetro y sus tipos individuales. Este tipo de documentación es inútil! Se necesitan segundos para que alguien lea el nombre de la función y los parámetros que se necesitan. Eso no es documentación, es sólo repetición. En su lugar, la documentación debe incluir un poco de información rápida sobre lo que hace la función y cómo cambia cada parámetro el comportamiento de la función o por qué se necesita.

Sobre-documentación

El patrón opuesto también puede ser un problema grave. Para evitar escribir muy poca documentación, a algunos desarrolladores les gusta escribir la explicación de cada pequeña parte de la lógica que contiene una función. Documentan meticulosamente todas las razones que se utilizaron para crear la función. Para cuando hayan terminado, es posible que hayan pasado tanto tiempo escribiendo la función como escribiendo la documentación. Lo que es peor, la documentación a menudo es difícil de entender y toma tanto tiempo como leer el código. Ese tipo de documentación también es una pérdida de tiempo. En cambio, una buena documentación da una explicación básica tanto del qué como del por qué. Si hay partes del código particularmente difíciles de entender, la documentación debería explicar solo esas partes.

Dependiendo de las pruebas para Documentar

De vez en cuando, te encontrarás con alguien que argumenta que la mejor forma de documentación son las pruebas unitarias. Ese enfoque tiene un defecto importante: la lectura de pruebas unitarias a menudo es tan difícil de hacer como la lectura del código en sí. Cualquier desarrollador que desee aprender lo que hace su código tendrá un gran primer paso mientras busca y lee todas sus pruebas unitarias. Muchos simplemente se rendirán antes de lograr lo que se propusieron hacer. Si bien las pruebas unitarias son una valiosa adición a cualquier base de código, no reemplazan una buena documentación.

Formas de llevar la documentación al siguiente nivel

Si trabaja con una gran base de código, la documentación de código puede resultar desalentadora, especialmente si no ha sido diligente en documentar el código hasta este momento. Puede parecer que estás tratando de hervir el océano. Si tiene una base de código grande, o una en la que sabe que una buena documentación es crítica, es posible que desee investigar las herramientas de documentación de código automatizada. Estas herramientas simplifican drásticamente el proceso de escribir documentación consistente y buena para todo un equipo. Una herramienta como GhostDoc mirará de forma inteligente tu código y utilizará plantillas establecidas por tu equipo para poner en marcha tu documentación con un par de pulsaciones de teclas. Las herramientas de documentación automatizada eliminan una de las otras razones comunes para oponerse a escribir documentación: lleva demasiado tiempo.

Una vez que tenga documentación coherente, otras herramientas le permiten compartir esa documentación fácilmente. Las herramientas de documentación automatizadas eliminan el dolor de desarrollar una buena documentación para cosas como las API públicas que proporciona el código.

Comience hoy

Escribir una gran documentación es mucho más fácil que escribir código. A diferencia del código, la documentación no es una empresa de todo o nada. Comience con el objetivo de escribir una buena documentación para una función todos los días. Ese tipo de práctica crea hábitos saludables, y verá la recompensa en el futuro cuando pase mucho menos tiempo tratando de comprender partes de su base de código. Con el tiempo, comenzará a sentirse mal cuando escriba código que no tenga buena documentación. Comenzarás a señalar formas de mejorar la documentación a tus compañeros de trabajo durante la revisión del código. Un pequeño hábito mejorará el código de su equipo para todo su negocio.

Descubra cómo GhostDoc puede ayudarle a simplificar sus comentarios XML, producir y mantener documentación de ayuda de calidad.

Sobre el autor

Eric Boersma

Autor colaborador

Eric Boersma es un desarrollador de software y gerente de desarrollo que ha hecho de todo, desde seguridad de TI en productos farmacéuticos hasta escribir software de inteligencia para el gobierno de EE. Le encanta hablar de las cosas que ha aprendido a lo largo del camino, y también le gusta escuchar y aprender de los demás.