Clean Code (Código Limpo) – Nomes

Nomes estão em todos os locais, estão em nossas variáveis, nossas funções e argumentos. Estão em nossas classes e pacotes. Pelo motivo de usarmos muito, é melhor a gente utilizar ele bem.

Escolher bom nomes leva tempo, mas ao final do processo de construção de software, salva mais que custa.

Use nomes com significados

O nome de uma variável, função ou classe deve responder a grande questão. Não da vida do universo e tudo mais. Mas o motivo dele/dela existir. Uma boa aqui é: se o nome precisa de comentário, não é um bom nome.

Ruim

int d; // elapse time in days
int fad; // file age in days

Bom

int elapseTimeInDays;
int fileAgeInDays;

Pode parecer simples, mas com poucas linhas de código os nomes começam a fazer toda a diferença

Ruim

public List<User> GetAll()
{
    List<User> newList = new List<User>();
    foreach (var user in theList)
    {
        if(user.Status == 5)
            newList.Add(user);
    }
    return newList;
}

O que é theList? Qual status é 5? O que o código faz afinal?
Se existem estas dúvidas, então temos que limpar o código sem adicionar complexidade.

Bom

public List<User> GetActiveUserFromFiles()
{
    List<User> activeUsers = new List<User>();
    const int ACTIVE_USER_STATUS = 5;
    foreach (var user in completeUserList)
    {
        if (user.Status == ACTIVE_USER_STATUS)
            activeUsers.Add(user);
    }
    return activeUsers;
}

Evite desinformação

Não se refira a um grupo de usuário por UserList ao menos que seja realmente uma lista. Algumas palavras têm significado para o programador. Então se esta variável não contem realmente uma lista, vai confundir o leitor.

Nomes grandes com pequenas variações também podem gerar confusão e devem ser evitados.
XYZControllerForEfficientHandlingOfStrings
XYZControllerForEfficientStoragesOfStrings
Estes dois nomes de variáveis acima podem e causarão confusão na cabeça do leitor.

Faça distinção significativa

Não é suficiente adicionar números em série ou trocar palavras, mesmo que o compilador esteja satisfeito. Se os nomes devem ser diferentes, eles também tem que significar algo diferente

Ruim

public void FindItensInArray(int[] a1, int[] a2) { }

Bom

public void FindItensInArray(int[] itensToFind, int[] arrayToSearch) { }

Se você tem uma chamada UserInfo e outra UserData não tem como supor qual delas vai retornar as informações que você deseja ou as vezes a mesma informação.

Devemos distinguir o nome de modo que o leitor saiba o que modificação causa na aplicação.

Use nomes pronunciáveis

Por padrão todo nosso código deve ser feito em inglês, isso não significa que podemos dar qualquer nome, temos que usar nomes que são pronunciáveis. Assim pode usá-los em uma conversa sem ter problemas.

Uma regra que eu gosto de usar é: não invente palavras nem abreviações.

Ruim

DateTime genymdhms;

Bom

DateTime generationTimestamp;

Nomes devem ser pesquisáveis

Nomes com uma única letra só podem ser usados dentro de pequenos métodos. O tamanho do nome deve corresponder ao tamanho do escopo.

Contantes devem estar contidas dentro de variáveis de fácil verificação

Ruim

if(daysWorked > 5){
   // do something
}

Bom

const int WORK_DAYS_PER_WEEK = 5;
if(daysWorked > WORK_DAYS_PER_WEEK){
   // do something
}

Evite mapeamento mental

Quem está lendo o código não deveria ter que mentalmente traduzir os nomes para algo que eles conhecem. Isso é um problema com variáveis que contem somente uma letra. Claro que dentro de um laço de repetição você pode usar i, j e k, se o escopo for pequeno não tiver conflito com outros nomes.
Neste caso específico o uso dessas variáveis já é algo conhecido mas fora desse contexto é uma escolha ruim.

Classes

Classes e objetos devem ter nomes com pronomes, como Customer, WikiPage, Account. Evite palavras como Manager, Processor ou Info no nome da classe. Nomes de classes nunca devem ser verbos.

Métodos

Este sim devem ser verbos ou frases verbais como PostPayment, DelegatePage ou Save.

Quando construtores são sobrecarregados prefira usar static factory com nomes que representam os argumentos.

Ruim

    class Session
    {
        private int sessionId = 0;
        public Session(int sessionId)
        {
            sessionId = this.sessionId;
        }
    }

Bom

    class Session
    {
        private int sessionId = 0;
        public static Session SessionCode(int sesionId)
        {
            return new Session()
            {
                sessionId = sesionId
            };
        }
    }

Não seja engraçadinho

Escolha sempre a opção que traga mais limpeza em vez de humor. Então não use Whack() para Kill() e não tente simplesmente ser engraçado como float away;

“Say what you mean. Mean what you say” (tradução ficou ruim, deixei em inglês)

Uma palavra por conceito

Escolha uma palavra para cada conceito abstrato e utilize-a por todo o código. Por exemplo, é bem confuso quando vemos um código que tem Fecht, Retrieve e Get para fazer coisas semelhantes.

Manter uma constância em seu código vai ser de grande ajuda a todos os que forem dar manutenção, inclusive você.

Fuja dos trocadilhos

Evite usar a mesma palavra para mais de um objetivo. Usar a mesma palavra para mais um significado é um trocadilho.

Seguindo o conceito anterior de uma palavra por conceito, podemos ter em um algoritmo o método Add() e um método Insert(), desde que cada um faça algo essencialmente diferente, então tudo bem.

Use nomes de Domínios

Lembre-se que a pessoal que vai ler seu código é um programador e por isso você pode usar termos da computação.

O nome AccountVisitor tem significado para programadores que conhecem o padrão VISITOR e praticamente qualquer programador entenderia algo como JobQueue.

Escolher nomes técnicos para as coisas técnicas é algo apropriado e encorajado.

Quando não existe um termo técnico, normalmente existe um termo usado no projeto ou solução. Pode não ficar tão claro para o leitor, mas fica fácil de tirar alguma possível duvida com os programadores mais experientes.

Adicione contextos significativos

Você pode adicionar contexto usando prefixos: addrFirstName, addrLastName, addrCity e assim por diante. Dessa maneira os leitores vão entender que este grupo de variáveis é parte de uma estrutura maior.

Claro que uma melhor solução é criar uma classe chamada Address e adicionar os métodos a ela sem os prefixos. Dessa maneira até o compilador vai saber que este grupo de variáveis pertence a um conceito maior.

Não adiciona contexto gratuito

No tópico anterior uma opção era colocar variáveis de mesmo prefixo isolados em uma classe. Caso este seja o caso, devemos então remover o prefixo “addr”. Dentro da classe Address eles não adicionam um novo contexto, então é desnecessário.

Nomes curtos geralmente são melhores que longos, desde que sejam claros. Lembre-se, nunca adicione mais contexto que o necessário.

Conclusão

A parte mais difícil de escolher bom nomes é que requem boas habilidades descritivas e conhecimento da cultura da empresa.

Por isso, leve um tempo para testar e escolher um bom nome. Quando estiver refatorando um código, use as ferramentas da IDE para testar um nome melhor. Esta é uma melhoria no código atual e vai continuar a ajudar a longo prazo.

Qualquer dúvida ou dicas, entre em contato: leandrolt@gmail.com

Referência
– Clean Code: A Handbook of Agile Software Craftsmanship (English Edition) – Robert C. Martin – Capítulo 2

Leave a Reply

Your email address will not be published. Required fields are marked *