RICHARD COLLAO

En algún momento todos hemos visto (o publicado) código difícil de leer al pedir ayuda en internet. No es raro: cuando algo no funciona, la urgencia gana. El problema es que muchas veces se comparte demasiado código, desordenado y sin contexto, lo que dificulta que otros puedan ayudar.

Este artículo es una guía rápida para evitar esos errores y escribir código más claro, mantenible y profesional.

1 - Documentar adecuadamente

Documentar no es escribir novelas, es explicar decisiones. Un buen comentario responde al por qué, no al qué.

“Ley de Alzheimer de la programación: si lees un código que escribiste hace más de dos semanas, es como si lo vieras por primera vez.”
— Dan Hurvitz

Herramientas como phpDocumentor permiten generar documentación automáticamente desde el código.

“El buen código es su mejor documentación.”
— Steve McConnell

2 - Convenciones de codificación

La consistencia es más importante que la preferencia personal.

• Variables → $smallCaps
• Clases → UpperCamelCase
• Métodos → lowerCamelCase
• Constantes → ALL_CAPS

Recomendación: seguir PSR-12.

3 - Identación y formato automático

Hoy no hay excusa para código mal formateado.

// VSCode
Shift + Alt + F

// PHPStorm
Ctrl + Alt + L

Automatizar el formato elimina discusiones innecesarias y mejora la lectura.

4 - Evitar el código espagueti

❌ Antes

<?php
$conn = new mysqli("localhost","root","","test");
$result = $conn->query("SELECT * FROM users");
while($row = $result->fetch_assoc()){
    echo "<div>";
    echo $row['name'];
    echo $row['active'] ? "Activo" : "Inactivo";
    echo "</div>";
}
?>

✅ Después

class UserRepository {
    public function getAll($conn) {
        return $conn->query("SELECT * FROM users");
    }
}

function renderUser($user) {
    $status = $user['active'] ? 'Activo' : 'Inactivo';
    return "<div>{$user['name']} - {$status}</div>";
}

Separar responsabilidades (datos, lógica y presentación) es clave.

5 - Herramientas modernas que deberías usar

Si trabajas sin estas herramientas, estás perdiendo tiempo y calidad:

• PHP CS Fixer → formatea código automáticamente
• PHPStan → análisis estático (detecta errores antes de ejecutar)
• Psalm → análisis avanzado de tipos
• Prettier → formato para frontend
• ESLint → reglas de calidad en JavaScript

Integrar estas herramientas en tu flujo (o CI/CD) eleva inmediatamente la calidad del proyecto.

6 - Buenas prácticas modernas

• Separación de responsabilidades (MVC o capas)
• Evitar mezclar HTML con lógica
• Usar clases en lugar de código procedural desordenado
• Aplicar principios SOLID cuando el proyecto crece
• Escribir código pensando en quien lo mantendrá (probablemente tú mismo)

Checklist antes de pedir ayuda

• ¿Reduciste el problema al mínimo posible?
• ¿El código está limpio y formateado?
• ¿Se entiende qué esperas vs qué ocurre?
• ¿Eliminaste código irrelevante?

Muchas veces, solo hacer esto te lleva directamente a la solución.

Recomendación final: “Código Limpio” — Robert C. Martin.

Escribir buen código no es solo hacerlo funcionar, es hacerlo entendible.

Saludos.