Los comentarios en el código son pecado mortal, o como nombrar tus variables, funciones y clases.

¿Sabias que comentar tu codigo en esencia es algo malo? Tantos años escuchando que uno debe comentar todo y ahora resulta que es lo contrario lo correcto? En 1995 el Sr. Tim Mas »

El tío de todos los programadores o como darse cuenta de que no eres en realidad un programador

¿Has escuchado o leído el nombre Robert C. Martin alguna vez? Si ud. es programador y no ha oído nunca mencionar a este hombre o a su trabajo déjeme decirle que lo Mas »

El nuevo Programador

¿Qué sentiste la primera vez que escribiste una línea de código y viste que un computador, como si fuera magia, hizo lo que tu querías? ¿Te acuerdas de esa sensación de estar Mas »

 

Los comentarios en el código son pecado mortal, o como nombrar tus variables, funciones y clases.

code-in-comments

¿Sabias que comentar tu codigo en esencia es algo malo?

Tantos años escuchando que uno debe comentar todo y ahora resulta que es lo contrario lo correcto?

En 1995 el Sr. Tim Ottinger escribió uno de los documentos mas descargados y respetados sobre este tema en el que introduce comentarios muy interesantes al respecto.

A diferencia de mi articulo anterior El tío de todos los programadores pienso hacer este completamente practico.

¿Alguna vez a visto esto o algo parecido?:

int d; // tiempo recorrido en dias 

¿Que sentido tiene crear un comentario al respecto o hacer una variable de un nombre tan poco descriptivo?, cuando puedes hacer esto:

int tiempoRecorridoEnDias;

Revelar tu intención.

Al nombrar en tu código debes revelar tu intención en el nombre, poner comentarios al frente significa que fallaste en el nombre de tu variable, es como el que cuenta un chiste y luego tiene que explicarlo falló completamente como humorista. Este problema se ve en nombres de variables como:

int mm; //meses del año
int yy; //año

o en nombres de metodos como:

function getYYYY(); que perfectamente pudiste simplemente llamar: getYear(); o getAño(); o extraerAño();

Existen otros nombres que escribes bajo contesto con referencias y por lo tanto te toca hacer esto:


//constante muy util para la velocidad
public static final int SPEED = 33.3333;

El decir que es una constante es completamente redundante, mencionar que es util (que obviamente debería) es irrelevante y al final no aclara ni siquiera de que se trata (¿velocidad de que exactamente?). Si quien lee tu código tiene que leer mas de tu código para saber a que se refiere una variable fallaste al nombrarla. escribir:


public static final int VELOCIDAD_DE_JUEGO = 33.3333;

El código se explica a si mismo y por lo tanto no hay necesidad de comentarios. Los nombres no están para que te sientas cura en día de bautizo, sino para comunicar tu intención y todos cada uno de ellos deben hacerlo.

Evitar la desinformación.

Los nombres no solo deben declarar intención sino que debes asegurarte de que están declarando la intención correcta. Nombrar tu clase por ejemplo: ManagerDeUsuarios y resulta que esa clase envía emails o hace validaciones o que en realidad guarda  en tu base de datos o lo que hace es crear un archivo de texto es un crimen ya que estas desinformando al usuario de la intencion de tu clase. A todas estas evítense nombres que empiezan con palabras como Manager, Data, Abstract, Service, que lo que dicen es realmente nada y demuestran que no sabias bien como llamar a tu clase.

Nombres pronunciables y evitar codificaciones.

Evite crear nombres de variables tales como ComrCrn el cual tal vez entienda usted porque está en contexto pero un nuevo desarrollador no entenderá para nada o evite convenciones, sufijos y prefijos tales como Qty_huevos o Cosina_xyz . Esta era una practica común hace 30 años cuando las aplicaciones debían ahorrar memoria con nombres mas cortos y los programadores gastaban tiempo valioso aprendiendo estas convenciones en vez de escribiendo código, pero ahora resultan ridículas, conflictivas e innecesarias.

Todos estos preceptos te evitan crear comentarios innecesarios y tener una base de como no nombrar, pero,  ¿como se deben nombrar entonces?

Clases y Variables.

Las clases y variables son entidades eso quiere decir que son sustantivos y por lo tanto deben tener nombres o frases de nombre como File o FileParser (las variables a veces contienen instancias de clases asi que te daras cuenta porque son tratadas de igual manera).

Métodos.

Los métodos deben ser verbos como actualizar(); o correr();

Booleanos.

Los booleanos tanto variables como metodos deben ser predicados, con la intención de que al ponerlos en un if statement sean elocuentes: if( animal.esGrande(tamaño); ) o if(animal.estaVivo) 

Para los enum como generalmente estan expresando estados lo mejor es ponerlos como adjetivos enum { AZUL, ROJO, AMARILLO}

Scope (Alcance).

El alcance de las variables te permite romper algunas de las anteriores reglas ejemplo:

function sumarNumeroASerie(Serie){
Numero n = new Numero();
Serie += n;
}

Cuando la variable es de uso solamente local, se puede usar diminutivos, ya que queda totalmente claro que es. El caso contrario cuando la variable es muy global debe ser muy descriptiva y dejar en claro para que sirve. (Imagínate una variable global que se llame n).

Con los metodos es todo lo contrario. Si son metodos locales lo mejor es que sean bien descriptivos ( Especialmente si son metodos privados) pero si son métodos globales lo mejor es que sean cortos y fáciles de llamar bebe.alimentar() en vez de bebe.tomarBiberonConLecheYAzucar();

Conclusión

Aclaremos algo. La idea de no usar comentarios es mas bien una sugerencia, una señal en el camino para guiarse. Si sientes que aun no puedes prescindir de los comentarios toma cada lugar donde uses comentarios como un recordatorio de que aun no has llegado al punto donde tu código es lo suficientemente expresivo. Es perfectamente normal para un principiante comentar todo lo que no entiende, solo mientras vayas aprendiendo mas a aclarar tu codigo es recomendable prescindir de estos.
¿Y que pasa cuando tenemos una función que no entendemos bien o es muy larga? Pues resulta que si tu función posee mas de 5 lineas de código probablemente la estas escribiendo mal ( Eso es otro articulo) y que por lo tanto tus funciones también deben explicarse a si mismas y ser fáciles de entender:


if(empleado.llegoTarde()){
jefe.regañar(empleado);
}

¿Que crees que se necesite comentar de la anterior función?
Si quieres leer el documento de Tim Ottinger aquí lo puedes encontrar. O en el libro de Robert C. Martin sobre naming que está inspirado en el mismo documento.

El tío de todos los programadores o como darse cuenta de que no eres en realidad un programador

unclebob

¿Has escuchado o leído el nombre Robert C. Martin alguna vez?

Si ud. es programador y no ha oído nunca mencionar a este hombre o a su trabajo déjeme decirle que lo mas probable es que está ubicado en el lado equivocado del río y que aun no sabe conceptos esenciales de programación, o que probablemente ni se pueda considera a si mismo como tal ( o por lo menos no como programador que maneje el paradigma de programación orientado a objetos).

Si, como lo escuchó. Es probable que ud. no sea programador aunque se considere serlo.

Y es que lo único que lo incluiría en la lista, si no sabe quien es este señor,  es que ud. lleve 40 años de experiencia programando día tras día como lo ha hecho él. Y si es así no le preste atención a este articulo y siga su camino, su majestad. O no, mas bien quédese; Créame que hasta un rey del código como usted puede aprender algo del viejo tío Bob, como es cariñosamente llamado por la comunidad del software en general este simpático señor.

Robert Cecil Martin nació en 1952, ha sido programador profesional desde 1970 y es asesor profesional internacional de software desde 1990. En estos últimos 20 años de su carrera, según sus propias palabras, Bob vivió 3 grandes revoluciones en el mundo del software ( en realidad el solo habla de 2, pero es porque es modesto.): La primera fue la que causó el libro Design Patterns: Elements of Reusable Object-Oriented Software escrito por GOF ( the gang of four, otro de las palabras que si ud. no ha escuchado es porque está al otro lado del océano en cuanto a saber de programación se refiere) en 1994 que sacó a la luz los famosos patrones de diseño, la segunda sería a comienzos del 2000 cuando se presentaron al mundo los principios de programación SOLID y la tercera la invención de las técnicas de programación de desarrollo ágil y extreme programming. De estas tres revoluciones Robert es protagonista de 2. Divulgó el concepto de los principios SOLID ( De los que hablaré mas profundamente en otros artículos futuros) y creó el famoso Agile y Extreme programming (Si señor, ya puede sorprenderse en caso de que tenga idea de que le estoy hablando.)

Pero… ¿Que tiene todo esto que ver con que yo le diga que ud no es programador?

Al buscar información en español sobre nuestro amado Bob en google no encontré mucho que roer. Es indiscutible que en cuanto a material que trate de desarrollo y arquitectura de software, estamos aun en gran desventaja con la que se encuentra en ingles reciente y de buena calidad. Aunque muchos de nosotros chapoteamos torpemente en el ingles, esto no solo trae una desventaja sobre el conocimiento al que tenemos acceso sino que también nos retrasa y nos aisla de las tendencias y hace que las discusiones que se tienen de ese lado ( en el que usted y yo no estamos) se presenten de una manera retardada o no se presenten en absoluto en nuestra comunidad latina y que por ende andemos enrevesados en conceptos de nuestro arte que estan desactualizados o que estamos usando de manera erronea. Le voy a presentar 3 y ud me dice si le suena de algo:

POO.

El programador latino típico cree que aprender a hacer programación orientada a objetos es saber usar clases e instanciar objetos y manejar conceptos como herencia, sobre carga, polimorfismo, encapsulación etc. Y que conocer estos conceptos te hace acreedor del titulo de programador en el paradigma orientado a objetos.

¿Que dice Uncle Bob?:

El paradigma de programación orientado a objetos no se basa en las Clases ni en las instancias de objetos. si no en la interacción entre estos por métodos que envían mensajes. Desde este punto de vista la programación orientada a objetos no se trata de guardar estados dentro de un objeto ( Prolongar la programación estructurada por medio de clases, que es lo que muchos están haciendo y llamando POO ) sino de interacción de comportamientos.

UML.

El programador criollo que todos llevamos dentro ( o que se sienta en el pupitre o cubiculo de al lado) cree que diseñar sistemas de software se trata de aprender UML y aplicarlo como diseño y a esto considera la técnica primordial ( y la primera que tiene que aprender, -_- ¿ me estas leyendo profesor de programación?)

¿Que responde Uncle Bob?:

Métase en la cabeza que el UML no es su diseño. Su diseño es su codigo. El UML es una abstracción para MODELAR su código desde diferentes puntos de vista. Ud. tiene que saber programar para poder modelar su sistema, no al revés.

MVC.

Un anillo para gobernarlos a todos, un anillo para encontrarlos, un anillo para atraerlos a todos y atarlos en las tinieblas. El MVC se ha convertido en la panacea en el mundo del programador de a pie. Olvidémonos de UML y de POO y de lo que sea; una vez se sabe que el modelo es la base de datos ( sigh, me dolió el estomago), que el controlador debe hacerte todo lo demas ( ¿por eso se llama controlador no?.. nooo??? ) y que la vista te muestra las cosas, ¿Para que me mato con conceptos complicados de programación que ni deben servir para nada. De porque el modelo vista controlador fala terriblemente a la hora de hacer aplicaciones extensibles hablaremos luego, pero veamos la respuesta del tio Bobby:

Si el modelo es su entidad que interactua con la base de datos, ¿donde debe ir su lógica de negocios? ¿donde esta su aplicación? ¿donde va su código que no es una entidad, ni un controlador, ni una vista?  ¿¿donde va su diseño????

Si todo esto, le despertó curiosidad, aunque poquito. Si, a pesar de que no le dí muchas respuestas, le creé un par de preguntas, es probable que usted necesite aprender un poco mas de este señor.

Desde: ¿Como se debe nombrar una variable o una función?, ¿Cuantas lineas de código debe tener una función?, ¿Porqué es pecado mortal y no vas a poder entrar al cielo de los programadores el dia que mueras sobre tu teclado si  usas switch e/o if anidados en una clase? ¿Como se debe organizar el codigo y las clases? ¿Como manejar las dependencias ( interacciones con otros objetos) para que mi código no se me enrede y pueda hacerle cambios rápidos y seguros cada vez que quiera agregar algo? ¿Que es refactoring?, ¿Inyección y manejo de dependencias? ¿Cuando y como debo usar unit tests?. Todo esto lo debes aprender por ti mismo, pero este señor te va a dar las bases para que sepas como.

Para los que ya dejaron de creer que programar se aprende en 21 dias y que se trata simplemente de escribir código hasta que funcione y no se entienda en absoluto como funciona su aplicación les dejo una frase y una ultima regla de uncle bob:

“Escribir código limpio es lo que usted debe hacer para poder llamarse a si mismo profesional”

¿Sabias que escribir comentarios en tu codigo es una mala practica y señal de que no eres buen programador? ( : O )

 

 

 

El nuevo Programador

preocupado

¿Qué sentiste la primera vez que escribiste una línea de código y viste que un computador, como si fuera magia, hizo lo que tu querías? ¿Te acuerdas de esa sensación de estar estrenando súper poderes que tuviste y del mundo de posibilidades que se abrió ante ti ?