El Valor de Documentación de código

Documentación de código es la colección de imágenes fáciles de entender y descripciones escritas que explican lo que hace una base de código y cómo se puede usar.

Puede ser simples comentarios explicativos sobre funciones y bloques, o un manual completo para desarrolladores, completo con un estilo prescriptivo de hacer y no hacer, descripciones generales de cada parte de la aplicación y enfoques para los tipos más comunes de tareas de codificación.

A menudo es mejor encontrar un medio feliz entre estos dos extremos cuando tomas la decisión consciente de comentar tu código y delinear las áreas más complicadas de una base de código en un lenguaje sencillo.

¿Por qué documentar su código?

¿Por qué tomarse la molestia de escribir sobre su código, en lugar de simplemente escribir código? ¿No sería más productivo de todos modos?

Puntos de guardado mental

La documentación es como un punto de guardado mental para esos momentos en los que finalmente obtienes lo que está pasando al final del día y no quieres perder impulso. Un código bien documentado asegurará que cuando necesite volver a sumergirse mañana por la mañana (o dentro de varios meses), no tendrá que tomarse tanto tiempo para ponerse al día.

El código documentado se reutiliza

La diferencia entre una biblioteca usada y una biblioteca no utilizada a menudo se reduce a su documentación.

¿Quién quiere usar una biblioteca de código abierto indocumentada o contribuir a un proyecto indocumentado? Casi nadie.

En la mayoría de los casos, preferirías usar una biblioteca menos potente que tenga documentos. ¿Por qué? Porque la documentación transmite otros puntos de información sobre una base de código. Los desarrolladores creen que el proyecto vale la pena el tiempo y la energía para escribir sobre él en un lenguaje sencillo para que cualquier persona que pueda estar interesada pueda comenzar rápidamente y aprender cómo funciona y por qué se tomaron decisiones clave.

Encontrar un proyecto nuevo, interesante y bien documentado en su idioma favorito puede ser muy emocionante y divertido. Veamos la alternativa extrema: tener que usar una biblioteca de código indocumentada y contribuir potencialmente a una base de código aparentemente bizantina… suena bastante doloroso, ¿verdad?

Entonces, ¿por qué no ha documentado su propio código?

Documentar el código es parte de escribir buen código

Una piedra angular del buen código es la capacidad de mantenimiento, lograda a través de documentación comprensible y legible.

Hay múltiples formas de documentar el código:

• elegir buenos nombres para variables y funciones
• dejar comentarios breves dentro del código para ayudar a dar contexto a futuros lectores
• agregar imágenes ilustrativas como diagramas de secuencia y relación de entidad
• proporcionar documentos de API, describiendo cada clase, método, argumento y valor devuelto
• utilizando un lenguaje de escritura estática, como TypeScript (tipos como documentación)

Compare dos ejemplos

Supongamos que obtiene algunos datos de una API de backend y los «ingresa», convirtiéndolos en una forma más útil para una interfaz de usuario de front-end. Esta es la primera de dos posibles soluciones.

// wdgt.jsexport const converter = (w) => { wdgtHdr = { name: w.nm, id: w.id, ts: w.lastTS } wdgtDtl = { dtlId: w.dtlId, dtlName: w.dtlNm, openTS: w.oTS, closeTS: w.cTS } wdgtRev = w.revs.map((r) => { const { note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = r const rr = { assocId: prsn1Id, assoc: `${prsn1Fn} ${prsn1Ln}`, amount: amt, note: note, revTS: cTS, } return rr } return { wdgtHdr, wdgtDtl, wdgtRev }}

El código anterior tiene el potencial de ser doloroso. Puede ver por el nombre que este es un tipo de convertidor que toma w como su parámetro.

Parece que devuelve un encabezado, tal vez detalles y algo llamado revoluciones. ¿De dónde salieron las revoluciones? Por supuesto, no hay detalles sobre los nombres de variable entrantes note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS… ¿o lo hay? Es rrla abreviatura de returned rev? Quién puede decirlo.

veamos el segundo ejemplo.

// widget_utils.ts// widgetConverter :: widgetRespDTO -> widgetexport const widgetConverter = (wResp: widgetRespDTO): Widget => { const widgetHeader: WidgetHeader = { name: wResp.nm, id: wResp.Id, ts: wResp.lastTS), // timestamp } const widgetDetail: WidgetDetail = { id: wResp.widgetId, name: wResp.dtlNm, openTS: wResp.oTS, // timestamp closeTS: wResp.cTS // timestamp } // is nested inside of WidgetRespDTO // .map -> const widgetRevisions: ReadonlyArray<WidgetRevision> = wResp.revs.map((wRevs: WidgetRevisionsRespDTO): WidgetRevision => { // how that other team names their variables...! const { cmt, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = wRevs const comment: string = cmt const associateId: string = prsn1Id const associateName: string = `${prsn1Fn} ${prsn1Ln}` const amount: number = amt const revisionTS: number = cTS // unix timestamp, and "closeTS" fyi return { associateId, associateName, amount, comment, revisionTS, } } return { widgetHeader, widgetDetail, widgetRevisions, }}

¡Qué diferente! Esta función está en un archivo util, por lo que el archivo principal ya está menos desordenado. También está escrito en TypeScript en lugar de JavaScript simple, por lo que tenemos el beneficio de las definiciones de tipos para ayudarnos a guiarnos.

Estamos convirtiendo widgetRespDTO s en widget s. Aunque acortado, tenemos pleno conocimiento de lo que es wResp. Estamos creando un widgetHeader y un widgetDetail, que es fácil de ver. También entendemos lo que son oTS y cTS. Podemos decir que WidgetRevisionsRespDTO s están anidados dentro de WidgetRespDTO.

Alguien muy amablemente cambió el nombre de las variables entrantes para que todos los que vean este código sepan lo que son. Finalmente, vemos que un Widget debe estar compuesto por el objeto {widgetHeader, widgetDetail, widgetRevisions} devuelto, ya que debe coincidir con el tipo de retorno Widget especificado en la parte superior.

¿Qué código te sentirías mejor usando?

¿Quién se beneficia?

El código bien documentado beneficia a muchas personas:

Desarrolladores junior

Debido a que está en un lenguaje sencillo y es fácil de entender, la documentación ayuda a los desarrolladores junior y a los nuevos miembros del equipo a sentirse seguros al saltar a una base de código. Esto evita la frustración y el abandono temprano de una tarea porque se complica demasiado rápidamente.

También es útil para los desarrolladores junior escribir su propia documentación para que puedan compartir su código con otros y para que puedan comprender mejor su código.

Desarrolladores senior

Al tomarse el tiempo para documentar ahora, los desarrolladores senior pasan menos tiempo explicando su código a otros en el futuro.

También pueden escribir código más complejo. La documentación en lenguaje sencillo permite a otros usarla como una caja negra, sin tener que entender el funcionamiento interno.

Equipos & proyectos de código abierto

Los cambios de personal pueden traer una tremenda desaceleración a un proyecto. Un código actualizado y bien documentado puede servir como seguro contra tales ralentizaciones y permitir que los miembros restantes del equipo den un paso atrás, revisen el código desde un alto nivel y decidan el mejor curso de acción para avanzar, y si es necesario, nuevos empleados a bordo.

Usted

Al documentar el código, debe resumirlo. Para resumir correctamente, debes ser capaz de entenderlo, sosteniendo las diferentes partes en tu cabeza al mismo tiempo. Escribir o contribuir a la documentación es un atajo para entender realmente una base de código, hacer grandes contribuciones y sentirse como una gran parte de un gran equipo.

Una buena documentación puede secar nuestra experiencia de codificación

Como programador, probablemente haya oído hablar del principio de No Repetirse como clave para escribir código limpio y conciso. En lugar de repetir el mismo bloque de código varias veces, escriba una función que se pueda escribir una vez y emplear en toda la aplicación.

De la misma manera, tu equipo y tú no deberíais encontraros con problemas similares y luego reinventar la rueda cada vez que intentéis resolverlos. Por ejemplo, alguna vez has escuchado a uno de tus compañeros de trabajo o te has encontrado diciendo:

«Agh, resolví algo muy similar a esto, pero nunca recuerdo cómo lo hago cuando surge… Probablemente debería escribirlo en alguna parte, ¿eh?»

Luego se encuentra escaneando los mismos hilos de desbordamiento de pila una y otra vez.

¡Sálvate a ti mismo y a tus compañeros de trabajo este dolor siguiendo el espíritu del principio SECO y escribiendo un documento que puedas emplear cada vez que surja el problema! Esto le ayudará a usted y a otros miembros de su equipo a ahorrar tiempo y a ser más efectivos a la hora de escribir código más sencillo, manejable y eficiente.

¿Cómo le ha afectado la documentación del código, o la falta de ella?