The Five Comment Smells
Los Cinco Malos Olores de Comentarios
C1: Inappropriate Information — use version control for history, not comments. C2: Obsolete Comment — stale comments are worse than no comments. C3: Redundant Comment — a comment that repeats the code adds noise. C4: Poorly Written — if a comment is worth writing, write it well. C5: Commented-out Code — delete it; git has history.
C1: Información Inapropiada — usa control de versiones para el historial, no comentarios. C2: Comentario Obsoleto — un comentario desactualizado es peor que ninguno. C3: Comentario Redundante — un comentario que repite el código añade ruido. C4: Mal Escrito — si un comentario vale la pena, escríbelo bien. C5: Código Comentado — elimínalo; git tiene el historial.
When to Comment
Cuándo Comentar
Good comments explain WHY, not WHAT. Legal notices, non-obvious intent, public API contracts, and TODO markers are acceptable. Everything else is a sign the code needs improving, not more comments.
Los buenos comentarios explican el POR QUÉ, no el QUÉ. Los avisos legales, la intención no obvia, los contratos de API pública y los marcadores TODO son aceptables. Todo lo demás es señal de que el código necesita mejorar, no más comentarios.
✏️
Code Challenge
Desafío de Código
Name each comment smell (C1–C5) before seeing the fix.
Nombra cada mal olor de comentario (C1–C5) antes de ver la solución.
💡 Key takeaway
Comments are not documentation — they are apologies. Prefer expressive code that speaks for itself.
Los comentarios no son documentación — son disculpas. Prefiere código expresivo que hable por sí mismo.