"No olvide documentar su código", "escriba comentarios", "los comentarios le ayudarán a usted cuando vuelva a tomar el código en 3 meses más". Estos son los consejos que suelen dar los académicos en las universidades cuando enseñan un lenguaje de programación a los estudiantes, al dar sus primeros pasos en la programación. Yo tengo unos comentarios que hacer al respecto
Un lenguaje de programación nos permite comunicarnos con la máquina. Asi podemos delegarle tareas tediosas al ordenador para que las repita in saecula seculorum. Al aprender un lenguaje de programación, la parte más difícil está en cambiar el interruptor, y pasar de pensar como humano a pensar como máquina. Tenemos que realizar ciertas abstracciones para aislar una tarea cotidiana que realizamos, y llevarla a una serie de pasos claros y simples que el ordenador pueda ejecutar, en su reino de caminos de alambres que entregan información a la CPU.
Esta información consiste en una serie de instrucciones íntimamente ligadas a la lógica, al álgebra de Boole, y al manejo de memoria. En un lenguaje de programación las instrucciones se articulan en un archivo de texto para que cuando sea ejecutado por el ordenata, uno reciba información clara y ordenada, a partir de información desordenada con que se alimenta al algoritmo.
Para cualquier novato en el asunto, este proceso resulta frustrante y requiere bastante esfuerzo, porque por una parte hay que memorizar un conjunto de instrucciones nuevas, y por otra hay que realizar este ejercicio de abstracción que el cerebro todavía no está acostumbrado. Uno debe imaginar qué es lo que sucede en cada iteración de un loop, para así identificar cuando son las condiciones de término del bucle, entre otras cosas.
Con tanta información por aprender, lo natural es que el código del estudiante no se vea profesional: porque el estudiante está aprendiendo algo totalmente nuevo. No se le ocurrirá nombrar bien las variables, tampoco indentar su código, ni seguir alguna convención. Es el mismo motivo por el cual aprendemos a caminar antes de correr.
Es cierto que frente al desorden que se observa en el código de los novatos, uno se ve tentado a pedirles que documenten su código. Pero esta petición le hace un flaco favor a los estudiantes, pues tanto que se lo repiten, que se les queda pegado y después más encima comentan mal. Pues en la universidad aprenden a programar y no tienen práctica en redacción.
El problema con estas reglas, es que esa no es la función principal de un comentario en el código fuente. Los comentarios son muchísimo más útiles para depurar su código fuente. Puede usar comentarios para bypassear partes intrincadas de su código fuente, y así identificar en qué punto está el error. Así como este truco, existen muchísimos más que se ayudan de los comentarios para poder encontrar errores en su código. Pero yo nunca los estudié en la facultad, fueron tácticas que tuve que desarrollar para ser más eficiente a la hora de programar.
Un lenguaje de programación tiene una diferencia sustancial respecto a un idioma, y es que uno puede componer e inventar las palabras que quiera.
Si esto lo podemos aplicar para que siguiendo la sintáxis del lenguaje que estemos usando, hagamos un programa expresivo: que el programa
Cuando comencé a ocupar Ruby on Rails fue que me di cuenta de esto. Cuando entendí sus convenciones: por ejemplo cuando un sustantivo está en plural se ocupa para controladores y vistas, mientras cuando está en singular se ocupa en modelos. Esto lo llevé más lejos a usar un sustantivo en plural cuando me refiero a un arreglo, y en singular cuando me refiero a un objeto. Un detalle tan pequeño como este, hace la diferencia entre una variable que se llama "lista_de_libros" y otra que es simplemente "libros". Posteriormente, revisando código de otros proyectos me di cuenta que esta pequeña regla no la usaba solo yo.
Permítame darle un ejemplo concreto de proyectos exitosos y otros no tanto. Kivy es un framework en Python que le permite a uno crear GUIs para Windows, Linux, Mac, e incluso móvil en sistemas android. Sorprendente, ¿no? Aquí puede ver el código fuente del proyecto. Fíjese como el código está perfectamente documentado con comentarios. En contraste, el framework Bootstrap apenas tiene comentarios en su código fuente, y son mucho más breves que en los comentarios de Kivy que abarcan más de 100 líneas consecutivas de código.
Si la calidad del código fuera directamente proporcional a la cantidad de comentarios -que es lo que pretenden numerosos académicos-, entonces Kivy debería tener más forks y estrellas que Bootstrap. Pero la realidad nos indica que Bootstrap tiene 72K forks, y Kivy 2.6K forks. También bootstrap supera en un orden de magnitud a Kivy en la cantidad de estrellas.
Pueden hacer la comparación también entre React Native y Kivy. Estuve revisando el código de RN, y si bien este tiene más comentarios que Bootstrap, no llega a ser tanto como los que hay en Kivy. Y los comentarios de RN hablan sobre los argumentos de las funciones definidas ahí y entrega ejemplos. Luego la parte de código está limpia.
Por último, resulta curioso que en el caso de Bootstrap se celebre que "la documentación que tiene sea fantástica". Es cierto, la documentación de Bootstrap es increíble (no exenta de errores, debo decir), pero hay que notar que esta está escrita aparte. No forma parte del código fuente del proyecto.
No quiero decir que la documentación haya que arrojarla por la borda, para nada. Es importante documentar el código, pero no es necesario hacerlo en el código mismo. Un código bien escrito es un código que al leerlo uno entiende lo que hace. Es necesario que se ocupen nombres para variables y funciones que hablen, que nos cuenten el algoritmo sin necesidad de notas a pie de página, que más encima oculten lo que hace el resto del código; como también seguir convenciones claras y que el equipo maneje.
La documentación como tal puede ir perfectamente en otros lugares. Por ejemplo si uno sigue el Test Driven Development, la documentación puede ir perfectamente en el test suite de nuestro proyecto. La documentación ahí nos dice qué es lo que hacen nuestras funciones, y las describen diciendo cómo deben funcionar. Otra herramienta que nos puede ayudar a esto es el buen uso de Git. Usando Git los comentarios si que se hacen superfluos, porque en cada commit vamos describiendo lo que hicimos, y en cada merge resumimos las funcionalidades añadidas y los problemas solucionados
El paradigma de programación más popular es el de Programación Orientada a Objetos, popularizado por Java. En mi candidez cuando estudié por fin este paradigma en la universidad, yo intentaba usar este martillo para atornillar los tornillos que veía. Pretendía que era una herramienta universal, cuando la POO es simplemente un martillo que nos va a servir muy bien cuando tengamos clavos, pero no cuando tengamos tornillos. Por eso que es fundamental aprender otros paradigmas, como la Programación Funcional, o aprender de decoradores que nos pueden servir para mejorar nuestra POO. Esto enriquece nuestro vocabulario en programación. Es como aprender la gramática de un lenguaje.
Lamentablemente, estas herramientas no se enseñan a utilizar en los institutos tradicionales de educación como las universidades. He conocido a ingenieros que han salido de prestigiosas universidades que no tienen idea de qué es el TDD, el programa Git o la Programación Funcional. Por lo tanto, es normal que de lo único que hablen sea de los comentarios.
Los programadores somos personas prácticas, aterrizadas en la realidad. "Si funciona, no lo arregle" puede ser la frase que mejor representa esto. A la mayoría de nosotros nos gusta escribir programas que solucionen problemas concretos. Profesores de la universidad: no nos pidan que escribamos poesía en los comentarios.