Documentación Técnica

Ahora conversamos Eber Irigoyen, Haarón González, Mario Cornejo, Samuel Arellano y Gabriel Flores sobre la documentación técnica en los proyectos de software. La ventaja de documentar, los documentos que nos exigen los clientes y/o jefes, ¿qué documentación realmente es útil? y otras formas de no gastar inútilmente nuestro tiempo.

code.png

Play

11 thoughts on “Documentación Técnica”

  1. Interesantes comentarios.

    En cuanto a comentarios de código, en días recientes hablé en el CETYS sobre algunas de las reglas de etiqueta que debemos considerar al programar con voluntarios que disponen de poco tiempo, en particular, en proyectos de Software Libre.

    Somos ingenieros, así que parte de la aversión de documentar es porque no le vemos utilidad inmediata. Ante tal, el siguiente planteamiento tiene utilidad: ¿Recordaría, yo mismo, lo que pretendía hacer con este código si volviera a verlo dentro de 5 años? Al menos, así lo planteé a los alumnos.

    Y explicaba que un comentario muy verdadero pero inútil es, como lo satiriza el comic de esta página:

    // Si h es cuartro, regresa -1
    if (h == 4) return -1;

    En un proyecto de código abierto es muy útil documentar la *intención* del código, es decir, como viene de la mente del autor.

    // Sólo debe haber tres párrafos.
    // Llegar al cuarto es un error.
    if (h == 4) return -1;

    Por último, en proyectos que son muy grandes, como LibreOffice, a mí me sirvió la documentación generada por herramientas como doxygen y opengrok, porque sin tener que hacer una corrida de escritorio manual puedo darme una idea del flujo del programa. Opengrok, porque puedo buscar la ubicación de símbolos según si se usan como referencia, definición, etc. También como doxygen, porque puedo ver gráficamente la relación entre clases. Ambos, con la ventaja de que permiten ver lo que el código hace, y no lo que el autor dice que hace.

    Buen podcast, buen tema!

    Saludos a todos!

  2. El problema llega cuando (como comente en el podcast) esa documentación no se mantiene al día y te encuentras cosas como:

    // Sólo debe haber tres párrafos.
    // Llegar al cuarto es un error.
    if (h == 5) return -1;

    Porque los requerimientos cambiaron, el código también, pero los comentarios no porque nadie los lee.

    El código no es el mejor lugar para la documentación. Generar documentación en base al código (actual) para entenderlo mejor eso es otra cosa y puede ser útil; pero comentarios en el código explicando el mismo código, por lo general, no lo es.

  3. @alvarezp en tu comentario de documentar la intencion, mas que eso creo yo que se debe tratar de hacer que el codigo mismo refleje la intencion, el hecho de tener comentarios en muchos casos es un code smell, tomando los comentarios del codigo, y aplicandolo al codigo mismo, se puede mejorar muchisimo, por ejemplo en vez de:

    // Sólo debe haber tres párrafos.
    // Llegar al cuarto es un error.
    if (h == 4) return -1;

    ese codigo tiene 3 problemas, una variable con un nombre que no me dice nada, y 2 numeros magicos; se aplicar algo como:

    if (numeroDeParrafos > MaxNumeroDeParrafos)
    return Error_FormatoInvalido;

    Y creo que en esta version los comentarios serian redundantes, porque el codigo ya me dice que esta haciendo

  4. Y mis comentarios finales al podcast, en mi opinion

    Hay tipos de documentacion que el programador no tendria que hacer, como los requerimientos o el manual del usuario, si te tienen haciendo estas tareas, estas haciendo trabajo que no te corresponde.

    Por otro lado, si te encuentras en una situacion donde estas trabajando largas jornadas porque no documentaron bien los requerimientos, estas pagando por el mal trabajo de otros.

    En ambos casos yo diria que al menos consideraras otras opciones.

    Tambien agregar que si tienes jefes que te piden documentacion tecnica del sistema solo porque tener documentacion los hace felices (se pueden justificar), como dice @ alvarezp, hay herramientas que te pueden generar bastante documentacion con poco esfuerzo, graficas, diagramas, etc. todos esos se pueden usar para esos propositos.

  5. Muy bueno el podcast, estoy de acuerdo con lo que comentaron Eber y Mario. En la universidad le metén a uno en la cabeza la idea de que hacer el manual técnico es buena práctica y que va a ser tu salvación cuando trates de hacerle mantenimiento a algún software, pero ya en el mundo real, no he visto al primero que para realizar esa tarea, se lea el manual.

    Me parece que algo que proporciona los beneficios que comentaron los participantes del podcast, es Behavior-Driven Development, que lo conduce a uno en el proceso más o menos así: Vision->Features->Acceptance Criteria/Tests->Unit Tests->Production Code. Esto permite que los roles principales: Stakeholders, Business analysts, Q&A/Testers, Desarrolladores contribuyan (en el mismo orden del proceso) y que de paso las especificaciones o pruebas automatizadas, en lenguaje ubicuo, conformen la documentación, tanto para la gente del negocio (features) y técnica (comportamiento). Por supuesto, es muy importante que esto se complemente con código de producción legible y autodescriptivo, como el ejemplo que da Eber arriba.

    En cuanto a los vídeos como recurso de referencia (que entrarían en lo que llaman “manual del usuario”) para el cliente u otras personas, me parece que solo deberían generarse en casos excepcionales, cuando realmente son necesarios, por ejemplo cuando es muy útil “observar” cómo otra persona hace algo paso a paso, y siempre deberían ser breves, para lo demás, es mejor la documentación escrita y con imágenes, así uno se puede detener, saltar o volver facilmente a los puntos apropiados. Los vídeos son para ver una vez y no más, la documentación escrita es más durable, es más efectiva como material de referencia.

  6. @Eber:

    Muy, muy cierto! Pero aún eso no está peleado ni demoniza los comentarios en código. Incluso siguiendo una buena práctica, como lo planteas, el número mágico sería una constante y en algún lugar hay que definir el valor de esa constante. Y ahí, surgirá la pregunta dentro de 5 años: “¿por qué rayos le habré puesto const MaxNumeroDeParrafos = 4 y no 3, como debía ser?”.

    Por ejemplo, es más fácil voltear un par de líneas hacia arriba y ver /* Corrige bug #76503 */ que tener que ir al DVCS y darle “vcs blame” y luego “vcs show” para ver el mensaje de commit (asumiendo que tenga uno y que el último commit haya modificado la línea de forma relevante) o incluso “vcs history file.c” y buscar la línea en cuestión.

    @Mario:

    Partir del principio de que el otro programador no es capaz sólo nos lleva a conclusiones negativas; nos truena cualquier posible escenario de análisis:

    * Cuando la documentación se genera automáticamente (si es que se genera), los metacomentarios podrían ser obsoletos.

    * Cuando se maneja un VCS, seguramente pondrá de mensaje de commit: “Cambié el archivo fulano.c” (si no es que lo deja en blanco).

    * Y por supuesto que no va a escribir código autoexplicativo, sino uno como el que yo propuse (jeje).

    Por eso parto del principio de que el otro programador es capaz y cometió un error o que estoy documentando para mí mismo.

  7. @alvarezp
    Como muchas de las veces el programador anterior no esta y no sabemos si fue capaz o no cuando escribió el código (puede que ya lo sea) es por eso que: “only in code we trust”.

  8. Me parece que algo que proporciona los beneficios que comentaron los participantes del podcast, es Behavior-Driven Development, que lo conduce a uno en el proceso más o menos así: Vision->Features->Acceptance Criteria/Tests->Unit Tests->Production Code. Esto permite que los roles principales: Stakeholders, Business analysts, Q&A/Testers, Desarrolladores contribuyan (en el mismo orden del proceso) y que de paso las especificaciones o pruebas automatizadas, en lenguaje ubicuo, conformen la documentación, tanto para la gente del negocio (features) y técnica (comportamiento). Por supuesto, es muy importante que esto se complemente con código de producción legible y autodescriptivo, como el ejemplo que da Eber arriba.
    +1

  9. Pingback: dev3cast - ponte

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *