Convenção de nomenclatura de artefatos

Question

Estamos fazendo um grande projeto no OSGi e adicionando alguns módulos comuns.Há alguma discussão sobre como nomear o artefato.

Então, uma possibilidade ao nomear o módulo é por exemplo:

cmns-definitions (para definições comuns), outra é cmns-definition, ainda outro é cmns-def.Isso também tem algum efeito no nome do pacote.Agora éxx.xxx.xxx.xxx.xxx.commons.definitions, se mudar para cmns-def seria xx.xxx.xxx.xxx.xxx.commons.def.

Dentro deste pacote estarão classes como enums e outras definições para serem usadas em todo o sistema.

Eu pessoalmente me inclino para cmns-definitions já que não há apenas uma definição dentro do pacote.Outras pessoas apontam que java.util não tem apenas 1 utilitário lá, por exemplo.Ainda, java.util é um abreviação para mim.Isso pode significar utilitário java ou utilitários java.A mesma coisa acontece com commons-lang.

Como você nomearia o pacote?Por que você escolheria esse nome?

1. cmns-definitions
2. cmns-definition
3. cmns-def

Pergunta bônus:Como nomear algo como cmns-exceptions?É assim que eu nomeio.Você poderia nomeá-lo cmns-xcpt?

EDITAR:

Estou lançando meus próprios pensamentos sobre isso na esperança de ser confirmado ou contradito.Se você puder, por favor faça.

De acordo com o que penso, a razão pela qual você nomeia algo é para facilitar a compreensão do que está dentro dele.Ou, segundo Peter Kriens, para facilitar a memorização e a capacidade de automatizar processos por meio de padrões.Ambos são argumentos válidos.

Meu raciocínio é o seguinte em termos de padrão:

1) Quando ocorrer uma substantivação e ela for bem conhecida no setor, siga-a na sua nomenclatura.
Por exemplo:"recursos" é um caso disso.Temos um módulo chamado cmns-features.Isso significa que temos muitos recursos neste módulo?Não.Significa "o módulo que implementa o arquivo de" recursos "do Apache karaf".
"commons" é uma substantivação de "comum" bem aceita na indústria.Não significa "muitos comuns".Significa "Código Comum".

Se eu vir extr-commons como um nome de módulo, sei que ele contém código comum para extr (neste caso, extração), por exemplo.

2) Quando uma quantidade de classes dentro do módulo estão cooperando para dar um significado distinto "um e apenas um" ao todo, use a forma singular para nomeá-lo.

A maioria dos módulos está incluída aqui.Se eu nomear algo como cmns-persistence-jpa, quero dizer que quaisquer classes internas cooperam juntas para fornecer a implementação jpa de cmns-persistence-api.Não espero 2 implementações dentro dele, mas na verdade uma infinidade de classes que juntas formam uma implementação.Cristalino para mim.Não?

3) Quando um agrupamento de classes é feito com o único propósito de reunir classes por afinidade, mas as classes não cooperam entre si sem propósito, use o plural.

Aqui é o caso, por exemplo, das definições de cmns (enums usados ​​por todo o sistema).

Alternativamente, o uso de uma abreviatura contorna o problema, por ex.cmns-def que também pode ser "interpretado expandido" por um leitor humano para definições de cmns.Muitas pessoas também usam "xxxx-util", que significa utilitários xxxx.

Ainda uma terceira opção pode ser usada para agrupar as coisas, usando um nome que por si só significa uma pluralização.A palavra “api” vem à mente, mas qualquer palavra que pluralize algo serviria, como “pack”.

O suporte para esses casos (3) são módulos bem conhecidos como commons-collections (usando o plural) ou commons-dbcp (usando abreviatura) ou commons-lang (novamente abreviatura) e qualquer coisa que use API para agrupar classes por afinidade.

Do apache:
commons-collections -> muitas estruturas de dados poderosas que aceleram o desenvolvimento dos aplicativos Java mais significativos
commons-lang -> host de utilitários auxiliares para a API java.lang
commons-dbcp -> pacote de vários pools de conexões de banco de dados

Answer 1

'é apenas um nome...'

Descobri em minha longa carreira que apenas esses nomes podem fazer uma tremenda diferença na produtividade.Eu não acho que faça diferença se você usar definições, definição, ou definição contanto que você seja consistente e use padrões no nome que sejam fáceis de lembrar e possam ser usados ​​para automatizar processos.Uma construção baseada em um esquema de nomenclatura consistente é infinitamente mais fácil de trabalhar do que uma construção com nomes de "agradável exibição humana" que são ad-hoc e não possuem nenhum padrão discernível.

Se você usar padrões, os nomes tendem a ficar mais curtos.Agora, as pessoas que trabalham com esses nomes geralmente passam muito tempo com eles.Portanto, a sua legibilidade não é tão importante quanto o seu valor mnemônico.Acontece que abreviações de 3 ou 4 caracteres são surpreendentemente poderosas.Uma das razões é que eles funcionam bem porque só existe uma abreviatura possível, enquanto se você demorar mais, haverá muitos candidatos.

De qualquer forma, a parte mais importante é a consistência geral.Boa sorte.

Answer 2

definitions (ou def ou definition) é um nome ruim porque não tem nenhuma semântica para o leitor.Você está em um mundo orientado a objetos (suponho) - tente seguir suas convenções e princípios.Os módulos no Maven devem ser nomeados de acordo com a maior "abstração" que eles contêm.“Definição” é uma forma, não um significado.

Sua pergunta é semelhante a:"Qual nome de classe é melhor FileUtilities ou FileUtils".Responder:nenhum.

Answer 3

Basicamente, o que você faz com as Definições e Exceções é fornecer uma espécie de API para seus outros módulos.Então proponho combinar definições, exceções e adicionar interfaces a ele.Então faz sentido chamar tudo de cmns-api.Normalmente prefiro os nomes no singular porque são mais curtos, mas você é livre para decidir, pois é apenas um nome.