Existem boas técnicas ou testes para nomear tipos?

Uma pergunta incômoda e aberta, mas é um problema contra o qual sempre me deparo:

O software fácil de manter e trabalhar é um software bem projetado. Tentar tornar um design intuitivo significa nomear seus componentes de forma que o próximo desenvolvedor possa deduzir a função do componente. É por isso que não nomeamos nossas classes "Tipo1", "Tipo2" etc.

Quando você está modelando um conceito do mundo real (por exemplo, cliente), geralmente é tão simples quanto nomear seu tipo após o conceito do mundo real que está sendo modelado. Mas quando você está criando coisas abstratas, mais orientadas ao sistema, é muito fácil ficar sem nomes fáceis de ler e de digerir.

Fica pior (para mim) ao tentar nomear famílias de tipos, com um tipo de base ou interface que descreve o que os componentes precisam fazer, mas não como eles funcionam. Isso naturalmente leva cada tipo derivado a tentar descrever o sabor da implementação (por exemplo, IDataConnectione SqlConnectionno .NET Framework), mas como você expressa algo complicado como "funciona por reflexão e procura por um conjunto específico de atributos"?

Então, quando você finalmente escolhe um nome para o tipo que acha que descreve o que está tentando fazer, seu colega pergunta "WTF isso DomainSecurityMetadataProviderrealmente faz? "

Existem boas técnicas para escolher um nome bem-intencionado para um componente ou como construir uma família de componentes sem obter nomes confusos?

Existem testes simples que eu posso aplicar a um nome para ter uma idéia melhor se o nome é "bom" e deve ser mais intuitivo para os outros?

Para nomear, existem seis técnicas que comprovadamente funcionam para mim:

1. gaste muito tempo inventando nomes
2. usar código comentários
3. não hesite em renomear
4. gaste muito tempo inventando nomes
5. usar código comentários
6. não hesite em renomear

PS. Caso a sua API seja pública, as opções acima se aplicam antes disso, porque, você sabe,

"APIs públicas, como diamantes, são para sempre. Você tem uma chance de acertar, então dê o melhor de si ..." (Joshua Bloch, Como criar uma boa API e por que é importante )

Meu teste básico é se você pode descrever a função da variável usando apenas palavras da variável:

por exemplo, se DomainSecurityMetadataProvider "Fornece metadados de segurança de domínio" ou "Fornece metadados relacionados à segurança de domínio", é bom.

No entanto, existem nuances que variam de pessoa para pessoa:

por exemplo, para mim, original_team_code é o código para a equipe original, enquanto para outra pessoa pode ser o código original para a equipe. Meu favorito pessoal era "UnsafeLegacyMutex", que não pude deixar de ler como "Este é um Mutex Legado que não é Seguro", em vez de "Este é um Mutex para o Código Legado ThreadUnsafe".

Portanto, meu teste estendido é escrever a variável em um fórum / wiki / chat e fazer com que as pessoas adivinhem o que isso significa.

Existem boas técnicas para escolher um nome bem-intencionado para um componente ou como construir uma família de componentes sem obter nomes confusos?

Na verdade não.

Uma dica, no entanto, é evitar a "voz passiva".

"DomainSecurityMetadataProvider" é passivo. Não há verbo, são todos os substantivos e substantivos usados ​​como adjetivos.

"ProvideMetadataForDomainSecurity" é mais ativo. Há um verbo.

A programação orientada a objetos é todo (realmente) substantivo-verbo. Substantivo == objeto. Verbo == método. Portanto, um nome de classe geralmente é muito "substantivo". Quebrar esse hábito e começar a inserir verbos é difícil.

Existem testes simples que eu posso aplicar a um nome para ter uma idéia melhor se o nome é "bom" e deve ser mais intuitivo para os outros?

Sim. Você definiu um excelente teste em sua pergunta. Pergunte a outras pessoas.

Antigamente, chamamos isso de "passo a passo do design". Foi um grande negócio suado em uma metodologia em cascata. Atualmente, com os métodos Agile, deve ser uma colaboração comum entre o autor e os usuários de uma classe. Não demora (e não deve) demorar muito. Discutir o design (e os nomes) antes de escrever os testes (e o código) reduzirá o fator de espanto e pode impedir os WTFs.

Usando um dicionário de sinônimos

Muitas vezes vou me referir a um dicionário de sinônimos ao fazer um novo desenvolvimento, a fim de encontrar palavras apropriadas para descrever minhas classes e métodos.

Classes que contêm principalmente lógica de operação

Costumo nomear classes que fornecem principalmente métodos de operação em uma estrutura de verbo substantivo, como "EntityProvider", "EntityLocator" etc.

Essas classes geralmente não contêm muito estado.

Classes que contêm estado

As telas da interface do usuário e as entidades de dados geralmente são com estado e, portanto, eu simplesmente nomeio essas classes com um padrão substantivo ou adjetivo-substantivo.

Exemplos: Person, Employee, CurrentEmployee, FormerEmployee

Classes de utilidade

As classes que contêm apenas métodos estáticos são geralmente consideradas classes "utilitárias", portanto, eu as nomeio consistentemente com o sufixo "Utilitário".

Exemplos: NetworkUtilities, FileUtilities

Testes

Não tenho bons testes para decidir se algo é mal nomeado, mas sugiro que tente usar um único substantivo e / ou um verbo único no nome e depois pense se esse substantivo / verbo descreve com precisão o que você ' renomear.

Se você achar que há mais na classe / método que não é capturado pelo nome, talvez essa classe / método precise ser refatorada.

Alan Green e Jeff Attwood escreveram sobre os males das classes de nomes com o sufixo "Manager". Eles argumentam que o termo "gerente" é usado em excesso e é muito vago para transmitir algo significativo. Eu tenho que concordar.

O artigo de Jeff também fornece uma lista de diretrizes sugeridas no Code Complete de Steve McConnell.

variáveis

Recentemente, experimentei nomes de variáveis ​​/ parâmetros descritivos mais longos que incorporam preposições, como "Of", "By", "For" etc. Alguns exemplos são mostrados abaixo:

string firstNameOfEmployee;

string lastNameOfEmployee;

// here I nimbly avoid worrying about whether to call it "Id" or "ID" :)
int idOfEmployee;

decimal amountForDeposit;

Account accountForDeposit;

Acho que isso funciona bem com o recurso intellisense do Visual Studio, facilitando a digitação desses nomes longos. Também acho que há menos duplicação de prefixos de nomes de variáveis ​​(por exemplo, personID, personFirstName, personLastName vs. idOfPerson, firstNameOfPerson, lastNameOfPerson), fornecendo um "hash" melhor que torna o intellisense ainda mais útil.

Então, quando você finalmente escolhe um nome para o tipo que você acha que descreve o que está tentando fazer, seu colega pergunta "WTF esse DomainSecurityMetadataProvider realmente faz?"

Que tipo de nome você espera para uma classe complexa e específica de domínio? Isso é tão bom quanto é possível sem tornar o nome da classe uma sentença (o que fará todo mundo pensar que você deu muita responsabilidade a uma única classe)

Eu consideraria retirar o provedor do nome. Se mencionar especificamente metadados, todo mundo já sabe que você está usando reflexão. Você pode torná-la uma palavra mais concisa (ou possivelmente mudar para outra palavra - é mais um consumidor do que um provedor do que você escreveu)

Use metáforas para descrever partes do sistema. Não apenas fará com que você descubra novas analogias, como ajudará a nomear mais facilmente.

(Sei que esse não é um exemplo forte, mas de qualquer maneira). Por exemplo, você pode chamar uma variável ou um tipo como mailbox, que serve como uma fila para as mensagens recebidas de uma classe.

Uma coisa em que eu seria muito firme é que NUNCA deve ser permitido que os Nomes estejam incorretos. O melhor exemplo, durante algumas re-fatorações, muito código foi alterado e algumas variáveis ​​começaram a se referir a algo diferente do que seus nomes sugeriam.

Muito em breve, um programador estava gastando idades e usando algumas chamadas de banco de dados muito caras, tentando obter certos dados que já haviam sido extraídos e armazenados. Renomeei tudo e, de repente, conseguimos remover uma tonelada de lógica complicada e com bugs.

Felizmente, casos em que você tem que pensar tanto sobre os nomes são raros. Quando esses casos surgirem, basta escrever um parágrafo explicando o que a classe faz. Ao contrário dos comentários em função ou do nível de função, o objetivo principal de uma classe raramente muda, portanto o risco de comentários ficarem desatualizados é relativamente pequeno. Então, você pode escrever alguns parágrafos ou desenhar ASCII para explicar o que a classe faz.