La Comprensión Comienza con Nombres Expresivos

30 de septiembre de 2019 • 4 min de lectura

En 2018, me uní a un proyecto grande a mitad de su desarrollo. Los ingenieros originales se habían ido dejando atrás código enrevesado y sin documentar. Trabajar con este tipo de código es desafiante porque no puedes diferenciar la fontanería del dominio de negocio. Esto hace que la depuración sea difícil y los cambios impredecibles porque no conoces el impacto. Es como tratar de editar un libro sin entender las palabras.

Muchos ingenieros creen que la medida del éxito es cuando el código compila. Yo creo que es cuando otro ingeniero (o tú en seis meses) entiende el “por qué” de tu código. Los ingenieros originales limitaron a los futuros ingenieros al no documentar y usar nombres confusos. Los nombres son a veces la única ventana al proceso de pensamiento del ingeniero anterior.

Donald Knuth dijo famosamente:

Los programas están destinados a ser leídos por humanos y solo incidentalmente para que las computadoras los ejecuten. – Donald Knuth

Nomenclatura

Nombrar es difícil porque requiere etiquetar y definir dónde y cómo encaja una pieza en una aplicación.

Phil Karlton, mientras estaba en Netscape, observó:

Solo hay dos cosas difíciles en Ciencias de la Computación: invalidación de caché y nombrar cosas.
— Phil Karlton

Vemos nuestro código a través de la lente de las palabras y nombres que usamos. Los nombres crean un lenguaje para que el siguiente ingeniero comprenda. Este lenguaje pinta una imagen de cómo el autor conectó el dominio de negocio y el lenguaje de programación.

Ludwig Wittgenstein, un filósofo de la primera mitad del siglo XX, dijo:

Los límites de mi lenguaje significan los límites de mi mundo. – Ludwig Wittgenstein

El lenguaje de nuestro software es solo tan descriptivo como los nombres que usamos y usar nombres vagos difumina el propósito del software; usar nombres descriptivos trae claridad y comprensión.

Imagina visitar un país donde no hablas el idioma. Una solicitud simple como pedir usar el baño trae miradas desconcertadas. La incapacidad de comunicarse es frustrante, tal vez incluso aterradora. Un ingeniero siente lo mismo cuando se enfrenta a nombres confusos, poco claros, o peor aún, engañosos.

Esta sensación se experimenta mejor.

Experiencia

Examina el primer fragmento de código, ¿qué hace este código? ¿Cuál es el por qué?

Tómate tu tiempo.

public class StringHelper
{
    public string Get(string input1, string input2)
    {
        var result = string.Emtpy;
        if(!string.IsNullOrEmtpy(input1) && !string.IsNullOrEmtpy(input2))
        {
            result = $"{input1} {input2}";
        }
        return result;
    }
}

El código anterior es una simple concatenación de dos cadenas. Lo que el código no te dice es el “por qué”. El “por qué” es tan importante, sin él, es difícil cambiar el comportamiento sin entender el impacto. Por supuesto, investigar el uso del código probablemente revelará su “por qué”, pero ese es el punto. No deberías tener que descubrir el propósito del código, en su lugar, el autor debería haber dejado pistas, es su responsabilidad hacerlo.

Revisitemos el código, pero con un poco de “por qué” espolvoreado.

De nuevo, tómate tu tiempo, observa la diferencia que sientes al leer este código.

    public class FirstAndLastNameFormatter
    {
        public string Concatenate(string firstName, string lastName)
        {
            var fullName = string.Emtpy;
            if(!string.IsNullOrEmtpy(firstName) && !string.IsNullOrEmtpy(lastName))
            {
                fullName = $"{firstName} {lastName}";
            }
            return fullName;
        }
    }

El “por qué” da vida al código, hay una historia que leer.

Comunicar

Comunicar la intención y el diseño al siguiente ingeniero permite que el software viva y crezca porque si los ingenieros no pueden modificar el software, muere. Esto es una tragedia, aún más cuando es resultado de un diseño pobre y falta de expresividad — cada uno es prevenible con conocimiento.

Hazle un favor al siguiente ingeniero y sé expresivo en tu código. Usa nombres descriptivos y captura el “por qué” porque quién sabe, el siguiente ingeniero podrías ser tú.