Anotações Capítulo 2: Nomes Significativos

Use Nomes que Revelem seu Propósito:

• O nome de uma variável, função ou classe deve dizer porque existe, o que faz e como é usado;

• Mesmo um método simples pode ser altamente difícil de compreender sem saber o contexto, sem saber o que é cada coisa, os valores possíveis, como usar o retorno do método:
  

public List<int[]> getThem() {
    List<int[]> list1 = new ArrayList<int[]>();
    for (int[] x : theList)
        if (x[0] == 4)
            list1.add(x);
    return list1;
}

• Apenas alterando os nomes podemos melhorar muito a compreensão sobre o mesmo código, como o caso do “game board”:

public List<int[]> getFlaggedCells() {
    List<int[]> flaggedCells = new ArrayList<int[]>();
    for (int[] cell : gameBoard)
        if (cell[STATUS_VALUE] == FLAGGED)
            flaggedCells.add(cell);
    return flaggedCells;
}

• Se adicionarmos classes a um código, ele pode ficar mais fácil ainda de compreender e podemos ainda pedir aos próprios objetos que retornem o que queremos, como o caso de adicionar a classe Cell com o método isFlagged:

public List<Cell> getFlaggedCells() {
    List<Cell> flaggedCells = new ArrayList<Cell>();
    for (Cell cell : gameBoard)
        if (cell.isFlagged())
            flaggedCells.add(cell);
    return flaggedCells;
}

Evite Informações Erradas

• “Devemos evitar passar dicas falsas que confundam o sentido do código”;
• Evitar palavras com significados não condizentes com o que desejamos;
• Exemplo: Só use o nome “accountList” para representar um grupo de contas, se realmente for uma lista (list), do contrário poderá confundir os outros, e seria mais apropriado usar um nome como “accountGroup” ou apenas “accounts”.
• “Cuidado com nomes muito parecidos": Fica dificil perceber uma pequena diferença entre “XYZControllerForEfficientHandlingOfStrings” e “XYZControllerForEfficientStorageOfStrings”, ambas são muito semelhantes e a diferença basicamente é a troca do “Handling” por “Storage”.
• “Usar conceitos similares para montar palavras é informação. Usar formatos inconsistentes para palavras leva a uma má interpretação”. Por exemplo, usar a letra “L” minúscula (“l”) que pode ser confundida com o número “1”, problema que poderia ser resolvido trocando o nome por algo que traga mais significado ao que estamos querendo representar.

Faça Distinções Significativas

• “Se os nomes precisam ser diferentes, então também devem ter significados distintos”:

Se precisamos representar duas coisas diferentes no mesmo escopo, não devemos escrever o nome errado de uma das coisas, talvez numa possível correção ortográfica o código deixe de compilar, ou então colocar nomes sequências como “a1, a2, …, aN”, já que esse tipo de nome é oposto de nomes expressivos, pois não oferecem informação alguma! Por exemplo:

public static void copyChars(char a1[], char a2[]) {
    for (int i = 0; i < a1.length; i++) {
        a2[i] = a1[i];
    }
}

• “Palavras muito comuns são redundantes”;
• O nome de uma variável jamais deve conter a palavra “variável”!
• O nome de uma tabela jamais deve conter a palavra “tabela”!
• Assim como “NameString” não é melhor do que “Name”, nenhuma trás mais significados ou expressividade do que a outra.
• Mesmo caso de “customerInfo” e “customer”, ou de “accountData” e “account”, nenhum dos nomes trás mais expressividade que o outro.

Use Nomes Pronunciáveis

• Crie nomes que sejam pronunciáveis!
• Isso vai contribuir para a parte social da atividade (programação), se os nomes não forem pronunciáveis como vamos poder discutir com outras pessoas sobre o código?
• Assim com variáveis pronunciáveis é fácil de discutir o código com alguém e também das pessoas entenderem o código mais facilmente e sem precisar pedir que expliquem o código.

Use Nomes Pesquisáveis

• Não devemos usar nomes curtos ou de apenas um caractere, no caso uma letra ou um número.
• Devemos sempre usar nomes longos que são fáceis de encontrar usando uma busca.
• Só é uma boa ideia, ou uma ideia aceitável usar nomes com uma letra só se esta for utilizada apenas dentro de um método pequeno como é o caso de um for.
• “O tamanho de um nome deve ser proporcional ao tamanho do escopo”:

Assim, se vamos utilizar uma variável em vários lugares de um código devemos ter um nome considerável, assim ela vai ser facilmente encontrada.

Evite Codificações

Não devemos utilizar nomes codificados, por que se usarmos vamos ter um trabalho a mais que é o processo de decifração.

A Notação Húngara

Prefixos de Variáveis Membro

Prefixos de membros, ou melhor prefixos de variáveis membro, nada mais é do que variáveis ou atributos de um objeto ou seja que são declarados na classe. Antes era preciso indicar que era uma variável membro (atributo) usando “m_” antes do nome da variável, hoje comumente usamos apenas o “this”.

Interfaces e Implementações

Temos aqui uma escolha de nomes para interfaces e implementações, poderíamos adicionar a letre “I” no início de um nome de uma interface para indicarmos que é uma interface, por exemplo, “IShapeFactory” porém é desnecessário e também quem vai utilizar as classes que implementam essa interface não precisam saber se é uma interface ou se é implementação, nesses casos podemos nomear a interface apenas com “ShapeFactory” e a implementação com o nome “ShapeFactoryImp” ou ainda “IShapeFactoryImpl”.

Evite o Mapeamento Mental

Na maioria dos contextos, um nome de uma só letra é uma escolha ruim. “Clareza é fundamental”.

Nomes de Classes

Classes e objetos devem ter nomes com substantivos, como cliente, conta e etc. Devemos evitar palavras como gerenciador, processador, dados ou info, não devemos usar verbos!

Nomes de métodos

Já os nomes de métodos devem ser verbos, como “postarPagamento”, “excluirPagina” ou “salvar”. Métodos de acesso devem ser nomeados com prefixos “get” e “set ou “is”.

Quando tivermos construtores sobrecarregados devemos usar métodos estáticos com nome que descreva os parâmetros, como:

Complex full = Complex.FromRealNumber(23.0);

Se precisar forçar o uso, mantenha os construtores privados!

Não dê uma de Espertinho

Não use brincadeiras, não seja muito “espertinho”, do contrário apenas pessoas que compartilham do mesmo senso de humor irão lembrar da brincadeira e entender o código. Devemos optar pela clareza no lugar de divertimento!

Selecione uma Palavra por Conceito

Escolha uma palavra por cada conceito (mantenha um padrão) abstrato e fique com ela, por exemplo, é confuso ter “pegar”, “recuperar” e “obter” como métodos equivalentes em classes diferentes.

Não faça Trocadilhos

Evite usar a mesma palavra para dois propósitos. Usar o mesmo termo para duas ideias diferentes é basicamente um trocadilho.

A ideia é não usar a mesma palavra com sentido diferente, no caso se em várias classes temos o método “add” que faz uma soma e concatenação de valores, não devemos dar o mesmo nome “add” ao um método que apenas adiciona um elemento numa lista.

Use nomes a partir do Domínio da Solução

Devemos usar nomes do domínio da solução, devemos utilizar termos técnicos da informática, de algoritmos, padrões e etc. Tendo em vista que quem vai ler o código são outros programadores e não os clientes, por isso não devemos utilizar os nomes que os clientes conhecem e sim os que são mais claros para outros programadores.

Use nomes de Domínio do Problema

Esse é um complemento do tópico anterior, existem casos que não temos um nome que os programadores não conhecem ou não estão acostumados, nesses casos devemos utilizar um nome do domínio do problema. Assim, em caso de dúvidas futuras, outro programador poderá simplesmente perguntar a qualquer especialista no domínio o que o nome significa.

Adicione um Contexto Significativo

Quando não conseguimos utilizar o contexto, podemos adicionar um prefixo ao nome, assim fica mais fácil entender o que realmente aquilo faz ou é! Por exemplo, o nome “state” para uma variável “estado” de um endereço, apenas pelo nome “state” não poderíamos compreender que é referente ao endereço, para melhorar isso podemos adicionar um prefixo e deixar o nome como “addrState”.

Não Adicione Contextos Desnecessários

Não adicione mais contexto a um nome do que o necessário! Se estamos trabalhando em um sistema com o nome “GSD”, não precisamos em toda classe adicionar esse prefixo, só vai dificultar as buscas e autocompletar o IDE que estamos usando.