Comenta tu mardito código

El código que escribes la mayoría del tiempo no se explica a si mismo, y muchas de las veces los comentarios que usamos explican muy poco de lo que estamos haciendo: Hacer comentarios en el código no es perder tiempo es ganar tiempo en un futuro

Las recomendaciones que el maese Ethan Muller destaca como importantes para comentar en el código son:

Código de alguien más

Si por ejemplo: haces copiar y pegar de algo de stackoverflow que no entiendas muy bien, pon el link al post y no tengas miedo. Seguro te será útil en un futuro.

Código que sea un poco (o muy) hack

Soluciones raras o poco convencionales que deberías de evitar pero bueno…nunca digas nuca y mejor comenta por qué hiciste esto.

Documenta los números mágicos

Los típicos

.menu { margin-top: 7px; line-height:30px } .menu-al-lado { margin-top: 3px; padding-top: 5px   }

¿Entonces qué cuál cifra tengo que cambiar después?
Es muy fácil caer en proyectos (sobre todo los que son muy grandes en poner números que ayuden a arreglar cifras que se contraponen)… un poco más sobre qué son los números mágicos y por qué los debemos evitar

Estilos relacionados con otros

Generalmente esto se traduce cuando tienes que sobre escribir una regla que habías definido anteriormente, por ejemplo:

.menu { text-decoration: underline; } .menu.note { text-decoration: none;   }

Trata de poner tus comentarios en inglés

Es probable que tu código legue a manos ajenas, y bueno, nosotros hablamos un mismo idioma y está bien escribirlo en el idioma común de tu equipo. Pero la de veces que me he encontrado en código en ruso y digo “Dayum ¿Qué quería decir este man (Piensa en otros)

Ejemplo en funcionamiento

/* Mal comentario */input:checked {/* Adds a 5px border to bottom of this element */border-bottom: 5px solid green; }
/* Buen comentario */input:checked {/* Adds "selected" indicator to this element */border-bottom: 5px solid green; }

Como verás el comentario no solo explica qué hace el código sino por qué hace eso el código.

Resumen del texto:
Let’s Write Beautiful CSS Comments
de Ethan Muller