Legibilidad de código y documentación

Justo que vi un comentario de Ixmael en el post sobre mis experiencias en rediseño de logos, me hizo recordar sobre la indentación y documentación al momento de escribir código. 

Con respecto a la indentación, el primer pensamiento que he notado en chavos que aprenden XHTML es Who cares!! Sin embargo, no importa si es XML, CSS, C++, JavaScript o lo que sea, indentar es definitivamente una buena práctica. En mi opinión:

  1. Te permite identificar fácilmente la estructura del código: bloques de procesos y sus sub-procesos internos o estructuración semántica del contenido (en XML o XHTML); lo cual,
  2. fomenta una construcción mental ordenada de lo que estás codificando/escribiendo. Este orden te permite extraer y concentrarte en solo un bloque particular, a groso modo si es el proceso grande o detallado si es un sub-proceso.
  3. Ayuda a descansar al lector en el proceso cognitivo de lectura-entendimiento (cuando no es el autor quien lee).

Con respecto a al punto 3, y esto de descansar o descargar cognitivamente al lector (usuario), pues ¿qué no es válido que exista un "diseño" en el código mismo? Diseñadores: si nos preocupamos en diseño editorial y de información por dar una estructura jerárquica a los textos, ¿por qué no hacerlo en códigos?

Quizá no haya tanta importancia entre

<head>

</head>

<body>

<body>

con

<head>

  </head>

  <body>

  </body>

Pero cuando las cosas comienzan a aumentar como en

<head>

     <title></title>

     <meta ...>

     <meta ...>

     <link ...>

     <script>

         bla bla bla...

     </script>

</head>

<body>

  <div id="hdr">

    <ul id="menu-principal">

        <li></li>

        <li></li>

        <li></li>

    </ul>

  </div>
  <div id="content">

    <div id="col-izq">

        <p> ... </p> 

        <p> ... </p> 

    </div>

    <div id="col-der">

        <p> ... </p> 

        <p> ... </p> 

    </div>

    </div>

    <div id="ftr">

        <p> ... </p>

        <p> ... </p>

    </div>

  </div>

</body>

pues no hay duda que indentar nos da una buena "ayudadita".

Ya en lenguajes completos (de aplicaciones) o de guiones (scripts), esto de la indentación es un must, sobretodo con esto de que no necesariamente seremos nosotros quienes lean nuestro código. Nunca está demás dejar la sangría necesaria, al menos para marcar cuándo empieza y termina un bloque de código y así:

  • diferenciar entre los grandes chunks de información (clases, métodos y funciones),
  • marcar bien los procesos repetitivos (ciclos for, while y repeat until), o bien, 
  • reconocer qué decisiones se tomarán a partir de ciertas condiciones (por ejemplo en if-then, switch-case o "ifs" anidados).

También está el asunto de estandarizar el cómo codificamos. Es algo bueno de aplicar en la mayor medida de lo posible por la misma razón del párrafo anterior, aunque también nos puede beneficiar a nosotros mismos: en algunos casos si dejamos las cosas enfríar un rato para luego retomar el trabajo, puede ser que ya ni nos acordemos qué es lo que escribimos o dónde nos queamos.

Por ejemplo, si tenemos muchas especificaciones en CSS, pues un

/*Footer*/

nos ayudaría a identificar que de ahí para abajo (hasta otra marca) son cosas que tienen que ver con el contenedor footer. Se que parece tonto, pero en mi caso cuando tengo una hoja de estilo con muchas cosas, ya ni ganas me dan de leerla.

Se ve con mayor claridad este asunto en las rutinas de programación. Por ejemplo, una cabecera ayuda a recordar qué estamos haciendo, o bien, si alguien más nos lee, al menos puede tener una idea de qué hay en el archivo aunque no lea detalladamente nuestro código.

/*****************************************************************

  Nombre: imprime_datos_usuario
  Fecha de creacion: 26-julio-2008
  Autor: Omar Sosa Tzec
  Entradas: strNombreUsr - Nombre del usuario.
            strDireccionUsr - Direccion del usuario.
  Salidas: intStatus - Verificador de que se imprimieron bien los datos en documento.
          1 si estuvo todo bien. 0 si hubo algun error.
  Descripcion: Recibe datos del usuario y entonces verifica que tienen validez consultando la tabla de usuarios validos y de ahi incrustarlos en el documento-mensaje de salida con la variable de estatus.
/*****************************************************************/

También en el manejo de variables, muchas veces resulta conveniente empezar éstas con algún identificador que de antemano nos diga de qué tipo es: un int para las variables enteras, un str para las cadenas, un flt para las flotantes o punto decimal, etc.

A partir de este punto, podemos hacer combinaciones de mayúsculas con minúsculas para nombrar las variables. Por ejemplo, fltResultadoDivision. Para otras palabras reservadas también podemos definir nuestros estándares. Por ejemplo, Persona para la clase persona y Pepe para nombrar un objeto de esta clase.

En CSS por otro lado, si son cosas que tienen que ver con un ID llamado header, por ejemplo, un estándar práctico es quizá ponerle fondo-hdr.gif a su imagen de fondo o en las especificaciones poner .deocor-hdr para llamar a una clase que aplica sólo en este ID.

Sí, ya se: puede ser un verdadero fastidio estar haciendo esto. Tampoco hay que exagerar, y dependiendo de qué estemos haciendo, tomar lo que se nos acomode mejor. Pero sin duda, un poco de estandarización y limpieza de código cae bien, sobretodo cuando se trabaja en equipo.