馃 Comentarios dentro del c贸digo

Dentro de un proyecto nada pude ser m谩s 煤til que buenos comentarios y simult谩neamente nada puede ser tan da帽ino para interpretar el c贸digo que comentarios que desinformen.

El prop贸sito de usar comentarios es el poder compensar la falta de expresividad del propio c贸digo. Por ello podemos decir que los comentarios son una forma de expresar un fallo como programador al momento de programar.

Cuando te veas en la necesidad de escribir comentarios preg煤ntate primero si existe una forma mas clara de expresar el c贸digo que acabas de escribir.

Los comentarios tienden a mentir en relaci贸n a lo que el c贸digo en realidad hace, y entre mas tiempo haya pasado desde que se escribi贸 el comentario mas alejado de la realidad est谩n. Los programadores tienden a mantener el c贸digo constantemente, no as铆 a mantener los comentarios.

El programador debe ser disciplinado al momento de programar para evitar utilizar comentarios como una forma de justificar la falta de interpretabilidad y simplicidad del c贸digo. Es preferible gastar el tiempo en mejorar estas falencias del c贸digo que en escribir comentarios.

Los comentarios que no tienen una verdadera relaci贸n con lo que el c贸digo hace son mucho peores que un bloque de c贸digo sin comentario alguno. Lejos de brindar entendimiento alguno solo enga帽an al lector. En ese sentido hay que entender que solo el c贸digo como tal indica que es lo que realmente se hace.

馃嵖 驴C贸mo escribir buenos comentarios en la programaci贸n?

馃イ Los comentarios no son una formas de maquillar el c贸digo

Una raz贸n com煤n para escribir comentarios es el escribir mal c贸digo. Debido al desorden y la complejidad de este para ser interpretado, escribimos comentarios de forma que estos expresen lo que a simple vista el c贸digo no puede expresar.

馃イ Expresa lo mas posible utilizando c贸digo

En ocasiones el c贸digo no logra expresarse de forma adecuada, por ejemplo.

// verificar si el empleado recibe beneficios por las horas trabajadas
if(empleado.horasSemanales > 40 && empleado.edad > 65)

Esto lo podemos simplificar de la siguiente forma.

if(empleado.esElegibleParaRecibirBeneficios())

馃イ 驴C贸mo escribir buenos comentarios en el c贸digo?

Algunos comentarios son necesarios y ben茅ficos, para determinar si un comentario es bueno o malo tenemos que determinar si el comentario fue la 煤nica forma posible en la que se pudo expresar la intenci贸n de un bloque de c贸digo.

馃イ Comentarios legales

En algunas ocasiones tenemos que escribir comentarios por razones legales, una de ellas es la informaci贸n del copyright. Cuando sea posible agrega solo una referencia a la licencia o cualquier documento externo en lugar de escribir todos los t茅rminos y condiciones dentro de los comentarios.

馃イ Comentarios informativos

Algunas veces es necesario proveer informaci贸n b谩sica cuando la expresi贸n no es tan intuitiva, una de ellas es la intenci贸n de las expresiones regulares. Sin embargo en la medida de lo posible utiliza funciones descriptivas.

馃イ Descripci贸n de intenci贸n

Algunas veces un comentario va mas all谩 de proveer informaci贸n de la implementaci贸n y provee informaci贸n acerca de la decisi贸n.

馃イ Clarificaci贸n

En algunas ocasiones es 煤til traducir el significado de alg煤n argumento oscuro o retornar un valor en algo que es le铆ble. Lo ideal ser铆a poder renombrar este argumento o valor de retorno, pero cuando esto no es posible debido a que por ejemplo forma parte de una librer铆a, podemos clarificar la intenci贸n mediante comentarios.

Se asume con lo anterior que al realizar comentarios que intenten clarificar se termine por conseguir lo contrario, esto ocurre con bastante frecuencia en los comentarios realizados en los escenarios de las pruebas unitarias.

馃イ Alertar sobre consecuencias

En ocasiones los comentarios nos pueden servir para alertar a otros programadores acerca de posibles consecuencias.

馃イ Comentarios TODO

Los comentarios TODO son tareas que el trabajador piensa que debe de hacer. Un TODO es una indicaci贸n a algo que se debe hacer, pero no es una raz贸n para escribir mal c贸digo y postergar su mantenimiento.

Muchos editores de c贸digo proveen funcionalidades para colorear y localizar los comentarios TODO a lo largo del proyecto de forma que pueda completarlos e irles removiendo del c贸digo.

馃イ Amplificaci贸n

Un comentario puede ser usado para amplificar la importancia de algo que de otra forma puede ser inconsecuente.

馃嵖 驴C贸mo identificar malos comentarios?

馃イ Murmullos

Agregar comentarios de este tipo en el c贸digo es solo porque se cree que es parte del proceso o como decoraci贸n del mismo.

Si se va agregar un comentario este tiene que tener un valor real, si una comentario requiere que se revise el c贸digo del m贸dulo, entonces podemos decir que el comentario no ha cumplido con su intenci贸n.

馃イ Comentarios redundantes

Evite los comentarios que describan lo mismo que describe la funci贸n, estos solo distraen y en ocasiones toma mas tiempo interpretarlos que la propia funci贸n que tratan de explicar.

馃イ Comentarios que desinforman

Algunas veces el programador realiza aseveraciones dentro de sus comentarios que pueden ser imprecisos.

馃イ Comentarios obligatorios

El requerir que cada funci贸n incluye comentarios produce una carga de l铆neas de c贸digo innecesarias que solo sirven para complicar el entendimiento del c贸digo o encaminarlo a otra direcci贸n.

馃イ Comentarios tipo diario

En ocasiones los programadores agregan comentarios al m贸dulo en forma de diario, de manera que estos comentarios van indicando la evoluci贸n de las actualizaciones del propio m贸dulo. Esto ten铆a sentido hace tiempo cuando no exist铆a el control de versiones, pero ahora que podemos ver este historial de forma detallada, no tiene sentido que se siga haciendo.

馃イ Ruido en los comentarios

Los comentarios tipo ruido son aquellos que no proveen ning煤n tipo de informaci贸n. Un ejemplo es.

/**
* Obtiene el dia de la semana
*/
protected getDiaDeLaSemana(){
}

Este tipo de comentarios no aportan y solo terminamos ignor谩ndolos.

馃イ Marcadores de posici贸n

Los programadores gustan de agregar este tipo de marcadores dentro de una posici贸n en el c贸digo. Por ejemplo…

// CONSTANTES //////////////////////////////////

En general este tipo de pr谩cticas deben de ser evitadas.

馃イ Comentarios en las llaves de cierre

Algunos programadores agregan comentarios enseguida las llaves de cierre } para indicar a que scope pertenecen. Esto pudiera tener sentido en grandes estructuras anidadas, pero en aquellas peque帽as (que es el caso recomendado) no son necesarias ni relevantes. Si se est谩n utilizando porque las estructuras son largas, lo mejor es achicar el tama帽o de estas.

馃イ Atribuciones

Los sistemas de versi贸n de c贸digo permiten determinar quien ha realizado cambios a trav茅s del tiempo en los diferentes archivos. Agregar comentarios para hacer esta labor es innecesario y no deber铆a realizarse.

馃イ C贸digo comentado

El c贸digo comentado no tiene sentido de existir. Cuando hacemos esto lo hacemos por el miedo a perder un bloque que pudiera ser 煤til, pero gracias al versionado de c贸digo podemos recuperarlo. Si hay un bloque que no esta en uso es mejor solo borrarlo.

馃イ Comentarios dentro del c贸digo HTML

Los comentarios dentro del HTML solo hacen mas dif铆cil el poder leerlo.

馃イ Comentarios que no est谩n relacionados con el c贸digo que les precede

Si se van a escribir comentarios, aseg煤rate que no sean comentarios que describan el c贸digo que no aparece a continuaci贸n. Evita comentarios dentro del c贸digo que describan el sistema en su forma general.

馃イ Demasiada informaci贸n

Evita discusiones hist贸ricas y descripciones irrelevantes dentro de los comentarios.

馃イ Cabeceras de las funciones

Las funciones cortas no requieren de mucha descripci贸n. Elegir nombres correctos y crear funciones cortas es mucho mejor que escribir comentarios en las cabeceras de las funciones.

Funciones Formateado de C贸digo
comments powered by Disqus