Ocurrencia: cinco porqués para documentar código

Hoy os propongo otro experimento que se me ha ocurrido a partir de una pregunta iniciada en la lista de correo de :

¿Existe alguna herramienta en la que pueda documentar mi código?

Como buenos ingenieros, la mayoría de las respuestas fueron eso: respuestas, es decir, referencias al código limpio o a herramientas concretas. Yo me he atrevido a proponer un experimento para averiguar colectivamente la causa raíz que nos empuja a querer documentar nuestro código. Yo tengo mi respuesta, claro, pero me parece interesante contrastarla y enriquecerla con los puntos de vista de los demás sin que entremos en el debate de “mi respuesta es más brillante que la tuya”. Así, la ocurrencia de hoy consiste en que os preguntéis los 5-porqués y los compartáis con todos mediante comentarios en este artículo.

Para no eternizar el experimento pondremos un “timebox” (tiempo límite) de una semana a partir de hoy y entonces trataré de hacer un resumen. Claro, será mi resumen, pero para matizar siempre está la caja de comentarios ahí abajo. 😉

  • 1.- Porque es mas rápido leer la documentación que intentar entender el código.
    2.- Porque tu yo futuro necesitará saber que decisiones tomaste.
    3.- Porque mañana podría atropellarte un autobús y el que viniera a sustituirte no sabría por donde coger tu código.
    4.- Porque si haces código abierto la gente podrá colaborar mas eficientemente.
    5.- Porque te obliga a tener disciplina y ser ordenado.

    • Hola Pablo,

      Bueno, en realidad la técnica de los 5 porqués se basa en hacernos la pregunta de “por qué” enlazada con la respuesta al anterior “por qué”. De esta manera profundizamos en el problema y tenemos más posibilidades de encontrar las causas subyacentes.

      Tus respuestas están muy bien pero seguro que podríamos profundizar preguntando: “¿Por qué es importante para tí entender el código?” o “¿Por qué es más rápido leer documentación que código?” y así, seguir profundizando.

      Un abrazo,
      JMB

    • Sobre tus 5 porques reales.

      Si el codigo esta bien escrito, debe ser mas sencillo de entender que los comentarios! Siempre que me encuentro con un codigo bien escrito (muchas mas que las veces que me encuentro con un codigo ofuscado, por suerte), los comentarios simplemente ni los leo. Sobre el punto 2, cada vez que uno escribe una linea, tiene que pensar si en un tiempo va a recordar que hace sin necesidad de documentacion, si eso no funciona habra que buscar la manera de hacerlo. Tu codigo deberia de ser posible de leer por cualquiera sin problema, algo esta mal al escribir el codigo si no es asi, y no es la falta de documentacion. 4 y 5 estoy de acuerdo aunque no veo que tienen que ver con escribir comentarios. Creo que el post en si va por el buen camino,

      documentar para los usuarios – correcto
      comentarios en el codigo, si necesitas explicar lo que haces, suele ser una indicacion de que algo estas haciendo mal o de manera enrevesada.

      • danibishop

        A veces tengo la sensación de que cuando se habla de “hacer código” se meten en un saco muchas cosas. No documentar un código basado en cálculos complicados, algoritmos derivados, etc., sobre todo cuando se hace un código que busca la eficiencia, es generalmente un crimen. Un algoritmo de Bresenham, siendo de los más intuitivos que hay, no se lee fácilmente en código. Y menos si es para ser embebido, por ejemplo.

      • Desde luego, pero incluso en los lugares mas “cientificos” la mayor parte del codigo no es asi, cuando es necesario escribir un algoritmo complicado o cosas por el estilo si es necesario a mi juicio escribir como has hecho todo y en que te basas, tampoco a un comentario por linea pero si la documentacion lo explica (al principio de cada funcion), puede incluso no ser tan necesario.

      • Pepe Doval

        Creo que un código “que no se entiende” tiene un problema de mantenibilidad más allá de si tiene documentación o no. Ponerle comentarios es probablemente el parche más sencillo, pero no resuelve mucho el problema. Cuando se intenta entender un código, normalmente es porque hace falta tocarlo o usarlo, y para eso los comentarios no ayudan mucho.

        Ayudan más, por ejemplo, los tests, porque aparte de usar un lenguaje más preciso, son también fáciles de mantener, extendiéndolos allí donde nuestro conocimiento sobre el código empieza a fallar.

      • Pepe Doval

        Hola, Dani, aunque estoy de acuerdo contigo (y hace muchos años que no uso comentarios), me gustaría hacer una puntualización. Lo ideal sería que los comentarios, como cualquier forma de documentación, no existan. El problema es que en el camino “hacia la perfección” todos estamos en algún punto intermedio, y determinadas “tiritas” están bien para solucionar tus dolores a corto plazo, aunque seas consciente de que te las quieres quitar más adelante.

        Es decir, que muchos de los “porqués” que podemos ver (como “tu yo futuro necesitará saber qué decisiones tomaste”) son reales y hay que atajarlos, y normalmente buscar la perfección no es el camino más corto para ello. Así que valoro muy positivamente las respuestas del tipo “documento porque no soy el programador perfecto”, ya que ninguno lo somos 😉

  • Hay que comentar el código.

    ¿Por qué? Porque por su propia naturaleza, el código informático no es tan rico como el lenguaje natural y se nota

    ¿Por qué? Porque muchas veces el código generado responde a consideraciones de contexto que no siempre pueden hacerse evidentes en el lenguaje de programación

    ¿Por qué? Porque el código es la concreción final resultado de una cadena de mensajes que parte en unas necesidades y que, en un 80% del recorrido, se formulan mediante lenguaje natural o símbolos no expresables mediante el lenguaje de programación al 100%

    ¿Por qué? Porque no todos los stackeholders, pasados, presente o futuros, de un proyecto software conocen (ni tienen por qué) las limitaciones del lenguaje de programación o las motivaciones que llevan a tomar ciertas decisiones.

    ¿Por qué? Porque eso implicaría a) que todo el mundo sería programador en última instancia, o b) que todos empleamos una sistematicidad perfecta que hace que nuestro código ‘nos hable’ así hayan pasado años desde que lo escribimos.

    [He respondido sobre la marcha y sin detenerme demasiado, a ver si así salía algo más parecido a un brainstorming. Saludos!]

    • Tras leer Clean Code, casi me he convencido de que el argumento de “los comentarios no se mantienen” y seguir la regla del buen Boy Scout hacen que mis “5 why” pierdan el 90% de su valor 😀

  • Pues yo estoy de acuerdo con no documentar, y salvo que tenga demasiada prisa o que no sea capaz de encontrar como dejar claro el código, no uso comentarios.
    Por otra parte tampoco suelo leer comentarios de los demás, si lo hago es de proyectos grandes que desconozco y en todo caso prefiero leer el código por que lo veo más fiable.

    Un saludo.

  • Pepe Doval

    Hola, JM,

    Me gustaría aportar mi granito, pero antes quiero dejar claro que soy de los que tengo hooks de git para evitar que se comiteen comentarios. En el caso de mi equipo, nuestra documentación va en los mensajes de commit, y allá va mi ejercicio de los 5 whys:

    1) ¿Por qué documentamos “algo” en los mensajes del SCV?

    Porque hemos encontrado que ese “algo”: (1) es información importante para nosotros y (2) no se transmite adecuadamente de otro modo en nuestro equipo. Para que quede claro, ese “algo” es: (a) intención del programador al hacer el commit, (b) justificación de las decisiones de diseño tomadas

    Lo hacemos en los mensajes del SCV porque es una herramienta que ya hemos usado y nos gusta la idea de tener esa info organizada en la misma historia que el código, que nos sirve incluso para ver la intención que tuvimos cuando hicimos algo hace meses, vamos que es útil 😉

    2.1) ¿Por qué esa info es importante para nosotros?

    Porque es conocimiento que valoramos para poder trabajar como equipo. Y como es una cuestión de valores no voy a profundizar más en esta rama 😉

    2.2) ¿Por qué no se transmite adecuadamente en nuestro equipo esa info?

    Porque no “pensamos” de la misma manera. Es decir, encuentro que, a pesar de ir ganando en madurez, todavía hay muchas cosas que unos expresamos de una forma en el código (y en los títulos de los commits!) y otros de otra. Dicho de otra forma, no tenemos un estándar de programación.

    3) ¿Por qué no hacemos código de la misma forma?

    Creo que puede haber muchos motivos, pero los voy a reducir a 2 principales: (1) llevamos poco tiempo juntos (2) no dedicamos suficiente tiempo a discutir sobre el código

    4.1) ¿Por qué llevamos poco tiempo juntos?

    Por circunstancias de la vida de las que ni siquiera los romanos son culpables. No voy a profundizar en esto porque es algo que en cualquier caso se solucionará solo con el tiempo 😉

    4.2) ¿Por qué no dedicamos suficiente tiempo a discutir sobre el código?

    De nuevo, varios posibles motivos, pero 2 principales: (1) no tenemos madurez (ouch, bucle!) para pairear a diario, y (2) dedicamos demasiado tiempo a tareas que no son programar

    5.1) ¿Por qué no tenemos madurez para pairear a diario?

    Esto va en bucle en relación a la madurez, llevar poco tiempo juntos, etc., pero evidentemente no es excusa para no “aprender” a hacerlo. Creo que este (5.1) tiene como causa esas presiones externas de tiempo que se reflejan en (5.2)

    5.2) ¿Por qué dedicamos demasiado tiempo (de trabajo) a tareas que no son programar?

    Por muchas razones más bien internas, que se pueden resumir en “tenemos una estructura legal errónea”. Puntualizo algunas de las razones para que se entienda: (1) tenemos una S.L. (2) tenemos una asesoría que no nos asesora (3) tenemos posibles clientes que nos piden papeleos innecesarios (4) tenemos un empleado (con lo que los “marrones” nos los comemos los socios, a pesar de ser los más “maduros” para tareas que no son marrones), etc.

    Para acabar, me gustaría comentar que la técnica de los 5 porqués nunca me pareció muy útil, porque no siempre (casi nunca!) es fácil dar una única rama. Yo en este ejercicio me he dejado ramas a propósito (en general las positivas, como que no tenemos tiempo para discutir sobre código porque dedicamos un mínimo semanal a “hacer” código, porque queremos entregar valor, etc.). Pero las ramas positivas también pueden llevar a identificar un problema o un waste. Por eso me gusta más la técnica de generar un árbol de “root-cause”, aunque claro, a ver quién te dejaba un comentario si pides eso xD

    Un abrazo!

    • Me ha encantado tu respuesta, Pepe. (Como siempre, por cierto). Muchas gracias por el ejercicio de sacar del contexto habitual (no se me había ocurrido incluir los comentarios en el control de versiones) y por el ejercicio de profundizar hasta el final.

      Estoy de acuerdo contigo en que probablemente hubiera sido más adecuado un diagrama de Ishikawa, por ejemplo, pero es lo que tiene publicar ocurrencias. 😉

  • Francho

    Yo soy de los que opinan que no hay que documentar más que lo imprescindible y siempre dentro del código.

    1.- porque es la forma más sencilla de que la documentación y el código se actualicen al mismo tiempo.

    2.- porque al tocar el código vemos la documentación que hay escrita sobre el. Eso si siempre que sea la justa.

    3.- porque un código bien escrito, con los nombres de clases, métodos y demás bien puestos se documenta a sí mismo. Aun así me gusta documentar los métodos y propiedades públicas con javadoc o similares

    4.- porque los comentarios de *doc (javadoc, phpdoc…) los utilizan los IDEs para facilitarnos la vida

    5.- porque los usan para el autocompletado, la ayuda en línea o, en ciertos lenguajes como php, algunos comentarios ayudan a los “inspectores de código” del IDE a detectar fallos en tiempo de escritura

    P.D: En cuanto a la herramienta, cada lenguaje tiene la suya. Por ejemplo para Android y Java uso Javadoc, para php PhpDoc, etc…

  • David Molina

    ¿Por qué comentamos el código?
    Para que no degenere con el tiempo.

    ¿Por qué no queremos que degenere?

    La respuesta es obvia: por temas de mantenimiento, costes, eficacia, rentabilidad, …

    ¿Por qué puede degenerar el código?
    Porque como toda creación tiene un ciclo de vida, y durante ese periodo suele haber cambios.

    ¿Que cambios?
    Cambios de enfoque, de necesidades, de programador…

    ¡Vaya! Me he quedado en la cuarta.

    En resumen, estoy de acuerdo en que el propio código es la mejor documentación posible en la mayoría de ocasiones. Una buena elección del nombre de métodos, funciones, variables, parámetros, atributos… y una buena segmentación del código es “la mejor documentación posible”. Puntualmente, puede surgir la necesidad de comentar algún algoritmo complicado, o algún paso, que la manera de proceder no sea la habitual.

    El problema de fondo: En general no sabemos trabajar en equipo, y no pensamos en manos de quien pueda caer el código. Por otro lado, en aplicaciones de gestión, no se suele aplicar correctamente la orientación a objetos (o no se sabe) y se suele caer en código muy procedural con métodos o funciones kilométricos.