¿Cómo escribir código mantenible de manera eficiente?

¿No es interesante encontrar en el código un comentario mal colocado e inútil?

¿Cómo podemos escribir pocos comentarios y aun así hacer que el código sea fácil de entender?

Una forma principal es hacer que el código se autodocumente. Cuando el código se autodocumenta, no se necesitan comentarios para explicar su función o propósito, y también hace que el código sea muy fácil de mantener.

En este artículo, proporcionaré algunas formas de hacer que tu código se autodocumente. A continuación se presentan tres métodos básicos para lograrlo:

Nombres: utiliza los nombres para explicar el propósito de variables, funciones, etc.
Encapsulación de funciones: encapsula el código con una funcionalidad específica en una función para aclarar su propósito.
Introducir variables: coloca expresiones en variables dedicadas.

Esto puede parecer sencillo, pero en la práctica puede resultar un poco complicado. Primero debes entender qué partes tienen problemas y en qué lugares se aplican estos métodos.

Además, aparte de los tres métodos anteriores, hay otras formas de aplicación más amplia:

Interfaces de clases y módulos: expón las funciones de las clases y módulos para que el código sea más claro.
Agrupación de código: utiliza grupos para distinguir diferentes fragmentos de código.

A continuación, mediante ejemplos, explicaremos concretamente cómo aplicar los 5 métodos anteriores en la práctica.

1. Nombres

Primero, veamos algunos ejemplos de cómo el uso de nombres hace que el código sea claro y se autodocumente.

1. Renombrar funciones

Nombrar funciones no es muy difícil; puedes seguir las siguientes reglas:

Evita palabras vagas, como "handle" o "manage" — handleLinks, manageObjects.
Usa verbos activos — cutGrass, sendFile — para indicar que la función ejecuta una acción.
Especifica el tipo de valor de retorno — getMagicBullet, READFILE. Los lenguajes fuertemente tipados también pueden usar identificadores de tipo para indicar el tipo de retorno de la función.

2. Renombrar variables

Especifica unidades — si hay parámetros numéricos, puedes añadir sus unidades. Por ejemplo, usa widthPx en lugar de width para indicar que la unidad de la anchura es píxeles.
No uses atajos — ni a ni b deben usarse como nombres de parámetros.

2. Encapsulación de funciones

A continuación, veamos algunos ejemplos de cómo encapsular código en funciones. Una ventaja de encapsular funciones es evitar la duplicación de código o mejorar la estructura del código.

1. Encapsular código en funciones

Esto es lo más básico: encapsula el código en una función para aclarar su propósito. Adivina qué hace la siguiente línea de código:

var width = (value - 0.5) * 16;

Parece no ser muy claro. Claro, con un comentario quedaría clarísimo, pero podemos encapsularlo en una función para lograr la autodocumentación...

var width = emToPixels(value);
 
function emToPixels(ems) {
    return (ems - 0.5) * 16;
}

Lo único que cambia es que el proceso de cálculo se trasladó a una función. El nombre de la función expresa claramente lo que hace, por lo que no es necesario escribir comentarios. Además, si es necesario, se puede llamar a esta función más adelante, logrando dos objetivos a la vez y reduciendo el trabajo repetido.

2. Usar funciones en lugar de expresiones condicionales

Las sentencias if que contienen múltiples operandos son difíciles de entender sin comentarios.

if(!el.offsetWidth || !el.offsetHeight) {
}

¿Sabes cuál es el propósito del código anterior?

function isVisible(el) {
    return el.offsetWidth && el.offsetHeight;
}
 
if(!isVisible(el)) {
}

3. Introducción de variables

Por último, hablemos de cómo introducir variables. Comparado con los dos métodos anteriores, este puede ser menos útil, pero de todos modos, saberlo es mejor que no saberlo.

1. Usar variables en lugar de expresiones

Mira este ejemplo

if(!el.offsetWidth || !el.offsetHeight) {
}

Ahora, en lugar de encapsular en una función, usamos variables introducidas.

var isVisible = el.offsetWidth && el.offsetHeight;
if(!isVisible) {
}

2. Usar variables en lugar de ecuaciones

También podemos usarlo para aclarar fórmulas complejas:

return a * b + (c / d);

Usa variables para reemplazarlo

var divisor = c / d;
var multiplier = a * b;
return multiplier + divisor;

4. Interfaces de clases y módulos

Las interfaces de clases y módulos — es decir, los métodos y propiedades públicas — son como una documentación que explica cómo usarlos.

Mira el siguiente ejemplo:

class Box {
    public function setState(state) {
        this.state = state;
    }
 
    public function getState() {
        return this.state;
    }
}

Esta clase también podría contener otro código. Puse este ejemplo a propósito para mostrar cómo la interfaz pública se autodocumenta.

¿Puedes decir cómo se invoca esta clase? Evidentemente, no es obvio.

Ambas funciones deberían tener nombres razonables que expresen su propósito. Pero incluso si lo logramos, todavía no queda muy claro cómo usarlas. Entonces es necesario leer más código o consultar la documentación.

Pero, ¿y si lo modificamos así...?

class Box {
    public function open() {
        this.state = open;
    }
 
    public function close() {
        this.state = closed;
    }
 
    public function isOpen() {
        return this.state == open;
    }
}

¿No es mucho más claro? Nota: solo cambiamos la interfaz pública; su representación interna es la misma que el estado this.state original.

5. Agrupación de código

Usar grupos para distinguir diferentes fragmentos de código también es una forma de autodocumentación. Por ejemplo, como se dice en este artículo, deberíamos definir las variables lo más cerca posible de donde se usan y clasificarlas siempre que sea posible. Esto también se puede usar para especificar las relaciones entre diferentes grupos de código, lo que facilita que otros sepan qué grupos de código necesitan entender.

Mira el siguiente ejemplo:

var foo = 1;
 
blah()
xyz();
 
bar(foo);
baz(1337);
quux(foo);

Compara con lo siguiente:

var foo = 1;
bar(foo);
quux(foo);
 
blah()
xyz();
 
baz(1337);

Al agrupar todos los usos de foo juntos, se pueden ver las relaciones de un vistazo. Pero a veces tenemos que llamar a otras funciones en medio. Así que, si es posible, intenta usar la agrupación de código; si no es posible, no lo fuerces.

6. Otras sugerencias

No uses marcadores extraños; los dos siguientes son equivalentes:

imTricky && doMagic();

if(imTricky) {
    doMagic();
}

Obviamente, la segunda es mejor. Los trucos de sintaxis no aportan ningún beneficio.

Nombra las constantes: si hay valores especiales en el código, es mejor darles nombres. var PURPOSE_OF_LIFE = 42;
Establece reglas: es mejor seguir las mismas reglas de nomenclatura. Así, quien lea el código podrá deducir correctamente el significado de varias cosas basándose en otro código de referencia.

Fuente: http://www.ido321.com/1360.html