A Compreensão Começa com Nomes Expressivos

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

Muitos engenheiros acreditam que a medida do 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 engenheiros futuros por 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 famosamente disse:

Os programas devem ser lidos por humanos e apenas incidentalmente para os 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 nomenclatura de coisas.
— Phil Karlton

Vemos nosso código através da lente das palavras e nomes que usamos. Os nomes criam uma linguagem para o próximo engenheiro compreender. Essa linguagem pinta um quadro de como o autor conectou o domínio de negócios e a linguagem de programação.

Ludwig Wittgenstein, um filósofo na 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 é tão descritiva quanto os nomes que usamos e usar nomes vagos obscurece o propósito do software; usar nomes descritivos traz clareza e compreensão.

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, pior ainda, enganosos.

Esse sentimento é melhor experimentado.

Experiência

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

Dedique 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 diz é o “porquê”. O “porquê” é tão importante que, sem ele, é difícil alterar o comportamento sem entender o impacto. É claro que 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 deles fazer isso.

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

Novamente, dedique 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ê” traz o código à vida, há uma história para ler.

Comunicação

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 um design ruim e falta de expressividade — cada um é evitável com conhecimento.

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