La comprensión comienza con nombres expresivos

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 tubería de la lógica empresarial. Esto hace que la depuración sea difícil y los cambios impredecibles porque no sabes el impacto. Es como intentar editar un libro sin entender las palabras.

Muchos ingenieros creen que la medida del éxito es cuando el código se 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 oscuros. Los nombres son a veces la única ventana al proceso de pensamiento del ingeniero anterior.

Donald Knuth famosamente dijo:

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

Nomenclatura

La nomenclatura 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: la 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 próximo ingeniero comprenda. Este lenguaje pinta una imagen de cómo el autor conectó el dominio empresarial y el lenguaje de programación.

Ludwig Wittgenstein, un filósofo en 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 tan descriptivo como los nombres que usamos y usar nombres vagos emborracha el propósito del software; usar nombres descriptivos aporta 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.

Este sentimiento 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 que, 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é” esparcido.

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 próximo 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 próximo ingeniero y sé expresivo en tu código. Usa nombres descriptivos y captura el “por qué” porque quién sabe, el próximo ingeniero podrías ser tú.