Si creías que Frank Abagnale Jr. (sí, hombre, el de “Atrápame si puedes”) era un mentiroso es porque no has leído mucho código comentado.
Los comentarios son la guinda del pastel a la hora de escribir mal código. Son, en sí mismos, un arte que debes dominar en sus dos vertientes fundamentales:
- Sobrecomenta. Escribe comentarios absurdamente innecesarios.
- Miente. Modifica el código pero no toques los comentarios. De esa manera conseguirás que los comentarios no tengan absolutamente nada que ver con lo que describen.
- Marea. Añade un largo histórico de cambios que a nadie le importan. Total, el Git y similares son para fracasados y cobardes.
- Conserva código obsoleto. Nunca jamás borres trozos de código. Mejor déjalo comentado y quede así para la historia.
Sobrecomenta
Es muy importante comentar mucho, pero mucho, mucho… mucho y mal.
Observa la belleza de este sencillo código:
private $variable1; // Declaración de la variable1
Es fabuloso todo lo que se consigue en una sencilla línea. Es un compendio de la sabiduría que hemos acumulado hasta ahora:
- Usar un nombre que no da ninguna pista de su utilidad. ¿Para qué leches servirá $variable1?
- Hacer el código menos legible. Nada mejor que añadir un comentario innecesario para distraer la vista y confundir aún más a quien se aventure a escudriñar nuestro código.
Otro clásico es éste:
// Bucle for. Usamos el contador $i
for( $i=0; $i<50; $i++)
{
...
}
¿Por qué explicar la razón por la que bucle acaba en 50? Eso mejor dejarlo a la imaginación del desdichado que lo lea. Eso sí, no olvides avisarle que está frente a un bucle, un bucle for para más señas.
Para menor claridad se puede incluso usar un nombre más apropiado para la variable $i:
// Bucle for. Usamos el contador $contadorBucle
for( $contadorBucle=0; $contadorBucle<50; $contadorBucle++)
{
...
}
Cuando lean esto sabrán que te estás riendo de ellos. ¿Te imaginas poder ver sus caras?
Miente
Dicen que mentimos unas doscientas veces al día (seguro que también es mentira), así que no tengas miedo, sabes hacerlo: miente en tus comentarios.
Cuando modifiques alguna parte del código que ya esté comentado no toques los comentarios que puedan existir. No importa lo grandes que hayan sido los cambios y que el código ya no tenga nada que ver con la explicación anterior. Los comentarios viejos no se tocan, son sagrados.
Marea
A todo el mundo le gusta leer largos trozos de comentarios insulsos y aburridos. Y no hablemos ya del histórico de cambios de una función.
¿Sabes lo frustrante que es tener que desplazarse a lo largo de páginas y páginas de comentarios hasta encontrar alguno útil o un pedazo de código que haga algo de verdad? Pues aprovéchalo.
Por desgracia los editores de hoy en día permiten desplazarse fácilmente entre funciones y hacen estos comentarios algo menos eficientes. Pero para todo hay una solución: pon los comentarios entremezclados con el código, siempre dentro de la función, nunca antes de su cabecera.
Conserva código obsoleto
¿Has decidido rehacer una función o un trozo del código? Para qué vas a borrar la parte que ya no usas. Deja ese código ahí. Nadie se atreve a borrar una línea de código comentada. ¿Por qué no la habrán borrado? ¿Estará ahí por alguna razón? Habiendo sistemas CVS por qué iba alguien a dejar un trozo de código viejo?
Deja que se devanen los sesos.
El remate
Saltea todo esto con chistes, insultos y referencias que nadie entenderá y tendrás una obra maestra.
Y si quieres ver lo que han hecho otros profesionales de echa un vistazo a ésto.