El Mal Necesario de los Comentarios

Un comentario es una disculpa. Cada vez que escribes uno para explicar código confuso, has fallado en escribir código claro. Los comentarios no se compilan — se pudren. El código cambia, el comentario no, y ahora es una mentira. El objetivo: expresar la intención con nombres y estructura, no con prosa.

int d; // elapsed time in days

int elapsedDays;

// ✗ Bad
function check(u):
    // if admin and active
    if u.r == "a" and u.s == 1:
        return true
    return false

// ✓ Good — no comment needed
function canAccessAdminPanel(user):
    return user.role == "admin" and user.isActive

Algunos comentarios se ganan su lugar. Avisos legales (copyright). Explicaciones de intención — el por qué de una decisión, no el qué hace el código. Advertencias de consecuencias ("No eliminar — esto es un parche para un bug conocido de la JVM"). Aclaración de regex o algoritmos complejos que no pueden simplificarse más.

// ✓ Legal — required by org policy
// Copyright (c) 2024 CleanKata Inc. MIT License.

// ✓ Intent — explains *why*, not *what*
// Using bubble sort intentionally — the data is almost always sorted
// and nearly sorted arrays run in O(n). Benchmarks in /docs/sort-perf.md
function sortReadings(readings):
    bubbleSort(readings)

// ✓ Warning
// Don't call this more than once per request.
// The payment provider charges per token generation.
function generatePaymentToken(orderId):
    ...

Los comentarios redundantes repiten lo que el código ya dice. Los Javadoc obligatorios en getters triviales son ruido: /** Retorna el nombre. */ getName() no aporta nada nuevo. El código comentado es lo peor: implica que algo es importante, pero nadie sabe si es seguro eliminarlo. Elimina el código muerto — git history lo recuerda.

// Increment counter
counter = counter + 1

function getName():
    // Returns the name.
    return name

// old_total = cart.items * price
// if discount: old_total *= 0.9
total = cart.calculateTotal()

counter = counter + 1

function getName():
    return name

total = cart.calculateTotal()

Reemplaza Comentarios con Código — cada comentario en esta función es una señal de alerta.