Diretrizes de nomenclatura de método conciso significativas

Recentemente, comecei a liberar um projeto de código aberto, enquanto eu era o único usuário da biblioteca que não ligava para os nomes, mas sei que desejo atribuir nomes inteligentes a cada método para facilitar o aprendizado, mas também preciso usar nomes concisos para que também sejam fáceis de escrever.

Eu estava pensando em algumas diretrizes sobre a nomeação, estou ciente de muitas diretrizes que se preocupam apenas com letras maiúsculas ou algumas notas simples. Aqui, estou cuidando das diretrizes para nomeação significativa, mas concisa.

Por exemplo, isso pode fazer parte das diretrizes que estou cuidando:

• Use Adicionar quando um item existente for adicionado a um destino, Use Criar quando um novo item estiver sendo criado e adicionado a um destino.
• Use Remover quando um item existente for removido de um destino. Use Excluir quando um item for removido permanentemente.
• Emparelhe os métodos AddXXX com os métodos RemoveXXX e Pair CreateXXX com os métodos DeleteXXX, mas não os misture.

Como mostram as amostras acima, eu gostaria de encontrar algum material on-line que me ajude com os métodos de nomeação e outros itens em conformidade com a gramática e os significados das palavras em inglês.

As orientações acima podem ser intuitivas para falantes nativos de inglês, mas, para mim, que o inglês é meu segundo idioma, preciso saber sobre coisas como essa.

Nomeação. Uma das coisas mais difíceis sobre desenvolvimento de software :)

Quando cito algo, aqui está o meu conjunto de prioridades:

• Siga os idiomas da minha língua. Ruby gosta de sublinhados. Javascript gosta de estojo de camelo. Qualquer que seja o idioma em que você esteja, é a convenção a seguir.
• Revela a intenção da API. Não é "send_http_data", é "post_twitter_status"
• Evite vazar detalhes da implementação. Digamos, prefixando uma variável com um tipo.
• Não usa mais caracteres do que o necessário sem quebrar as diretrizes anteriores.

Obviamente, essa é uma abordagem bastante simplista. A nomeação é diferenciada.

Para pesquisas adicionais, eu recomendaria a leitura de The Art of Readable Code , pois fornece alguns conselhos excelentes e sucintos sobre a nomeação de métodos. Para ainda mais pesquisas, não posso recomendar o Código Limpo de Bob Martin

A tentação de codificar um estilo ou convenção para nomear pode, em alguns casos, levar a hábitos considerados hoje uma prática ruim, como usar a notação húngara, por exemplo. A resposta simples é esquecer a convenção e o estilo de nomeação como se fosse algo separado a ser determinado separadamente e, em vez disso, concentrar-se em nomear tudo em seu sistema com base no que ele realmente representa. Os nomes dos métodos serão naturalmente concisos se você limitar a funcionalidade de cada método, de modo que ele faça apenas uma coisa em particular e se o nome do método realmente descrever a única coisa que o método deve fazer.

Variáveis, campos, nomes de classes e arquivos são outra coisa. Eu sugiro que, se os nomes das variáveis ​​estiverem ficando muito longos, você esteja tentando descrever esses itens com muito detalhe, ou eles representam algo complexo que deve ser dividido em partes menores ou talvez descrito de maneira mais abstrata maneira.

No final do dia, você deseja evitar códigos feios com nomes que ocupam uma linha inteira ou que sejam tão simples que roubem seu valor.

Para mim, encontrar um bom nome para algo sempre volta a pensar nele como um objeto que precisa justificar sua existência. Pergunte a si mesmo:

• O que a classe / método / variável faz, ou seja, qual é o seu objetivo mais amplo e para que serve?
• O que especificamente sobre seu propósito ele precisa se comunicar, ou seja, qual é a parte essencial que o nome precisa ter nele?

A maioria dos desenvolvedores concorda que a legibilidade é sempre de suma importância quando se trata de nomeação. Não basta escrever código para que você saiba o que quer dizer enquanto estiver escrevendo, para que alguém que esteja olhando o código pela primeira vez em algum momento no futuro saiba o que você quis dizer sem ter que pensar muito. Você escreverá o código apenas uma vez, mas durante sua vida útil, ele provavelmente precisará ser editado várias vezes e lido ainda mais.

O código deve ser auto-documentado, ou seja, sua nomeação deve tornar óbvio o que algo faz. Se você precisar explicar o que uma linha de código faz em um comentário e renomear as coisas não a melhorarem bastante, considere seriamente refatorar essa linha em um novo método com um nome descritivo apropriado, para que, lendo o método original, o Uma nova chamada de método descreve o que está acontecendo. Não tenha medo de ter nomes longos; é claro que você não deve escrever romances em nomes de classe / método / variável, mas prefiro que um nome seja muito longo e descritivo do que curto demais e preciso descobrir o que ele faz olhando sob o capô. Exceto por algumas exceções óbvias, como coordenadas x / y e acrônimos comumente usados, evite nomes e abreviações de caracteres únicos. Chamando algo "bkBtn" em vez de "backButton"

Tanto quanto seu idioma permitir, faça com que seu código seja lido como uma frase em inglês. Objetos usam substantivos, métodos usam verbos. Os métodos booleanos geralmente começam com "is", mas existem muitas outras opções que transmitem o significado ainda melhor, dependendo do caso de uso, como "can", "should" ou "does". Obviamente, nem todos os idiomas podem ser tão bons quanto o Smalltalk, mas alguns símbolos geralmente são entendidos como partes da frase. Duas convenções do Smalltalk que eu pessoalmente gosto de levar para outros idiomas, tanto quanto possível, são o prefixo do nome dos parâmetros do loop com "each" e o método do prefixo com o artigo "a" (ou "an" ou "some" para coleções) . Isso pode não ser um padrão comum em Java, e qualquer um pode ignorar esse bit, mas acho que isso melhora muito a legibilidade do código. Por exemplo (exemplo em Java):

public boolean shouldConsiderAbbreviating(List<String> someNames) {
  for (String eachName : someNames) {
    if (isTooLong(eachName)) {
      return true;
    }
  }
  return false;
}

Isso deve ser legível para pessoas com um pouco de conhecimento de Java, algo como isto:

Para determinar se você deve considerar abreviar uma lista de alguns nomes (que são cadeias), itere sobre alguns nomes e, para cada nome, determine se é muito longo; se sim, retorne true; se nenhum for muito longo, retorne false.

Contraste o código acima apenas nomeando o argumento stringse a variável loop string, especialmente em um método mais complexo. Você precisaria olhar atentamente para ver a diferença, em vez de o uso ser óbvio com uma olhada no nome.

Encontrar uma boa nomeação é sempre um compromisso entre mais fatores. Você nunca ficará totalmente satisfeito.

Dito isto, mesmo que seu idioma nativo não seja assim, considere que o inglês é o idioma cujos tokens das linguagens de programação são formados. O uso de sintaxe semelhante ao inglês torna a leitura de código mais "fluente", pois não existem "regras de leitura quebradas" toda vez que uma palavra-chave é encontrada.

Em geral, considere coisas como object.method(parameters)combinar com um esquema como subject.verb(complements).

O ponto principal, se você precisar oferecer suporte à programação genérica, é escolher um conjunto bom e consistente de "verbos" (especialmente aqueles que precisam ser usados ​​em algoritmos genéricos).

Sobre substantivos, as classes devem ser nomeadas pelo que elas are(em termos de conceito), enquanto objetos pelo que elas are for.

Dito isto, entre list.add(component)e component.add_to(list)prefira o primeiro. Em geral, os verbos "transitivos ativos" representam melhor as ações em relação aos seus homólogos passivos ou reflexivos. A menos que as restrições de design o concentrem.

Não se preocupe com o tamanho dos nomes dos métodos. Verifique se os nomes dos métodos refletem claramente o que estão fazendo. Isso é fundamental para qualquer outra coisa. Se você achar que o nome do método é muito longo, use um dicionário de sinônimos para encontrar uma palavra mais curta que signifique a mesma coisa. Por exemplo, use em Findvez de Retrieve.

Além disso, o mais importante são os nomes que você escolhe para suas aulas. Eles fornecem muito contexto ao examinar os nomes dos métodos. Uma assinatura de método como esta:

public User Find(int userId);

é mais fácil de entender do que:

public Person Find(int personId);

porque o contexto obtido do nome da classe Userinforma ao programador que Find()é para localizar um tipo específico de pessoa, o usuário do seu sistema. A versão que usa a Personclasse não fornece nenhum contexto sobre por que você precisaria usar o método em primeiro lugar.

Veja como outras pessoas na sua plataforma fazem isso - alguns dos maiores players podem até ter diretrizes de estilo e código de nomenclatura.

Algumas plataformas preferem nomes abreviados (por exemplo, na API Win32 C _tcsstré a função de encontrar uma sequência dentro de uma sequência - não é óbvio?), Outras buscam a legibilidade em favor da brevidade (na estrutura Cocoa da Apple para o Objective-C , o método para substituir uma substring em uma string por outra e retornar o resultado como uma cópia é chamadastringByReplacingOccurrencesOfString: withString: ). Acho o último muito mais fácil de entender e apenas moderadamente mais difícil de escrever (especialmente com a conclusão do código).

Como você lê código com mais frequência do que escreve (duplamente verdadeiro para bibliotecas de código-fonte aberto) e a leitura é mais difícil do que escrever, otimize-a. Otimize a brevidade apenas por último e retire apenas o máximo possível, sem diluir a clareza.

1. Suponha inglês, a menos que todo desenvolvedor que trabalhe nesse código fale o mesmo idioma que não o inglês.

2. Estude convenções e estilos de nomenclatura comumente aceitos. Seu princípio orientador deve ser a clareza. Os estilos diferem de acordo com a linguagem de programação.

3. Não há nada que você possa fazer com a nomeação que facilitará o entendimento dos relacionamentos entre os vários objetos no seu código. Para isso, você ainda precisa de comentários e documentação bem escritos.

1. Use prefixo. Se vários métodos forem usados ​​para fazer algo semelhante ou puderem ser agrupados de alguma forma, coloque um prefixo comum antes dos nomes para mostrar o que esses métodos têm em comum.
2. Não use abreviações pouco claras se quiser que outras pessoas entendam os nomes instantaneamente (importante na nomeação de API)