O Entendimento Começa com Nomes Expressivos

Em 2018, entrei em um grande projeto na metade do seu desenvolvimento. Os engenheiros originais haviam saído deixando para trás código complicado e sem documentação. Trabalhar com esse tipo de código é desafiador porque você não consegue diferenciar a infraestrutura do domínio de negócio. Isso torna a depuração difícil e as mudanças imprevisíveis porque você não conhece o impacto. É como tentar editar um livro sem entender as palavras.

Muitos engenheiros acreditam que a medida de sucesso é quando o código compila. Eu acredito que é quando outro engenheiro (ou você em seis meses) entende o “porquê” do seu código. Os engenheiros originais prejudicaram os futuros engenheiros ao não documentar e usar nomes obscuros. Os nomes são às vezes a única janela para o processo de pensamento do engenheiro anterior.

Donald Knuth disse famosamente:

Programas são feitos para serem lidos por humanos e apenas incidentalmente para computadores executarem. – Donald Knuth

Nomenclatura

Nomenclatura é difícil porque requer rotular e definir onde e como uma peça se encaixa em uma aplicação.

Phil Karlton, enquanto estava na Netscape, observou:

Existem apenas duas coisas difíceis em Ciência da Computação: invalidação de cache e nomear coisas.
— Phil Karlton

Vemos nosso código através das lentes das palavras e nomes que usamos. Nomes criam uma linguagem para o próximo engenheiro compreender. Esta linguagem pinta um quadro de como o autor fez a ponte entre o domínio de negócio e a linguagem de programação.

Ludwig Wittgenstein, um filósofo da primeira metade do século 20, disse:

Os limites da minha linguagem significam os limites do meu mundo. – Ludwig Wittgenstein

A linguagem do nosso software é apenas tão descritiva quanto os nomes que usamos e usar nomes vagos obscurece o propósito do software; usar nomes descritivos traz clareza e entendimento.

Imagine visitar um país onde você não fala a língua. Um pedido simples como pedir para usar o banheiro traz olhares perplexos. A incapacidade de se comunicar é frustrante, talvez até assustadora. Um engenheiro sente o mesmo quando confrontado com nomes confusos, pouco claros, ou ainda pior, enganosos.

Este sentimento é melhor experimentado.

Experiência

Examine o primeiro trecho de código, o que este código faz? Qual é o porquê?

Tome seu tempo.

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;
    }
}

O código acima é uma simples concatenação de duas strings. O que o código não te diz é o “porquê”. O “porquê” é tão importante, sem ele, é difícil mudar o comportamento sem entender o impacto. Claro, investigar o uso do código provavelmente revelará seu “porquê”, mas esse é o ponto. Você não deveria ter que descobrir o propósito do código, em vez disso, o autor deveria ter deixado pistas, é responsabilidade dele fazer isso.

Vamos revisitar o código, mas com um pouco de “porquê” polvilhado.

Novamente, tome seu tempo, observe a diferença que você sente ao ler 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;
        }
    }

O “porquê” dá vida ao código, há uma história para ler.

Comunicar

Comunicar a intenção e o design para o próximo engenheiro permite que o software viva e cresça porque se os engenheiros não conseguem modificar o software, ele morre. Isso é uma tragédia, ainda mais quando é resultado de design pobre e falta de expressividade — cada um é evitável com conhecimento.

Faça um favor ao próximo engenheiro e seja expressivo no seu código. Use nomes descritivos e capture o “porquê” porque quem sabe, o próximo engenheiro pode ser você.