Convenção de nomenclatura para classes utilitárias em Java

115

Ao escrever classes de utilitários em Java, quais são algumas boas diretrizes a serem seguidas?

Os pacotes devem ser "util" ou "utils"? É ClassUtil ou ClassUtils? Quando uma aula é um "Ajudante" ou um "Utilitário"? Utilitário ou utilitários? Ou você usa uma mistura deles?

A biblioteca Java padrão usa utilitários e utilitários:

javax.swing.Utilities
javax.print.attribute.AttributeSetUtilities
javax.swing.plaf.basic.BasicGraphicsUtils

O Apache usa uma variedade de Utilitários e Utilitários, embora principalmente Utils:

org.apache.commons.modeler.util.DomUtil
org.apache.commons.modeler.util.IntrospectionUtils
org.apache.commons.io.FileSystemUtils
org.apache.lucene.wordnet.AnalyzerUtil
org.apache.lucene.util.ArrayUtil
org.apache.lucene.xmlparser.DOMUtils

Spring usa muitas classes Helper e Utils:

org.springframework.web.util.UrlPathHelper
org.springframework.core.ReflectiveVisitorHelper
org.springframework.core.NestedExceptionUtils
org.springframework.util.NumberUtils

Então, como você nomeia suas classes de utilitários?

java naming-conventions

— JR.
fonte

82

Como muitas dessas convenções, o que é importante não é tanto qual convenção você usa, mas que você a usa consistentemente. Por exemplo, se você tem três classes de utilitários e as chama de CustomerUtil, ProductUtils e StoreUtility, outras pessoas que tentam usar suas classes vão ficar constantemente confusas e digitar CustomerUtils por engano, ter que procurar, xingar você algumas vezes, etc. (Eu ouvi uma palestra sobre consistência uma vez em que o palestrante colocou um slide mostrando um esboço de seu discurso com três pontos principais, rotulados como "1", "2º" e "C".)

Nunca, jamais, faça dois nomes que diferem apenas em algumas sutilezas de grafia, como ter um CustomerUtil e um CustomerUtility. Se havia uma boa razão para fazer duas classes, então deve haver algo diferente sobre elas, e o nome deveria pelo menos nos dar uma pista de qual é essa diferença. Se um contém funções utilitárias relacionadas a nome e endereço e o outro contém funções utilitárias relacionadas a pedidos, chame-os de CustomerNameAndAddressUtil e CustomerOrderUtil ou algo parecido. Eu regularmente fico louco quando vejo diferenças sutis e sem sentido nos nomes. Como ontem, eu estava trabalhando em um programa que tinha três campos para custos de frete, chamados "frete", "custo de frete" e "frete". Tive que estudar o código para descobrir qual era a diferença entre eles.

— Jay
fonte

9

E IV para o número 4 :-) - Mas qual era a diferença entre frete , custo de frete e frete ?

— KajMagnus

4

@KayMagnus Essa postagem foi há mais de um ano, mas, pelo que me lembro, um deles era o custo do frete atual no registro, antes de alterar o conteúdo do pedido e, portanto, potencialmente o custo do frete; outro era o custo de frete padrão tirado de uma tabela; e o terceiro era um custo calculado usado em alguns casos especiais, como remessas para o exterior. Tipo, por que eles não poderiam pelo menos chamá-los, digamos, "currFreight", "stdFreight" e "calcFreight". Isso teria pelo menos dado uma pista.

— Jay

Ok, obrigado pela explicação :-) Um exemplo de código estranho interessante, eu acho

— KajMagnus

31

Não existe uma regra / convenção padrão no mundo Java para isso. No entanto, prefiro adicionar "s" no final do nome da classe como @colinD mencionou.

Isso parece bastante normal para o que o mestre da API Java Designer Josh Bloch faz (coleção java, bem como coleção do Google)

Enquanto Helper e Util continuarem, chamarei algo de Helper quando tiver APIs que ajudam a atingir uma funcionalidade específica de um pacote (considerando um pacote como para implementar um módulo); significa enquanto um Util pode ser chamado em qualquer contexto.

Por exemplo, em um aplicativo relacionado a contas bancárias, todas as APIs estáticas de utilitário específico de número iriam para org.mycompany.util.Numbers

Todas as regras de negócios específicas de "Conta" ajudando APIs iriam para

org.mycompany.account.AccountHelper

Afinal, é uma questão de fornecer uma documentação melhor e um código mais limpo.

— portador do anel
fonte

5

Isso parece razoável, que Helper seria mais específico que Utils.

— KajMagnus

1

Sim, gosto dessa abordagem, é mais lógica.

— Conan

3

O link está quebrado. Eu encontrei outro .

— Chavjoh

22

Eu gosto da convenção de apenas adicionar "s" ao nome do tipo quando o tipo é uma interface ou uma classe que você não controla. Exemplos disso no JDK incluem Collectionse Executors. É também a convenção usada nas coleções do Google.

Quando você está lidando com uma classe sobre a qual você tem controle, eu diria que os métodos utilitários pertencem à própria classe em geral.

— ColinD
fonte

2

O Google Guava também usa esse padrão

— Jherico de

11

Eu acho que 'utils' deve ser o nome do pacote. Os nomes das classes devem especificar o propósito da lógica dentro dela. Adicionar o sufix -util (s) é redundante.

— Aito
fonte

2

Isso não seria a coisa certa a se fazer em uma abordagem de 'pacote por recurso' .

— jpangamarca

1

@jpangamarca O artigo que você vinculou contém um pacote "util" no exemplo de 'pacote por recurso'. Acho que, na prática, algum tipo de recurso / camada de utilidade geralmente não pode ser evitado.

— Kapex

1

@kapex Um descuido do autor, eu acho. Um tld.organization.app.utilpacote não deveria existir (poderia, mas não deveria), qualquer número de tld.organization.app.feature.utilpacotes é perfeitamente adequado.

— jpangamarca

3

Tenho certeza de que as palavras "ajudantes" e "utilitários" são usadas alternadamente. De qualquer forma, a julgar pelos exemplos que você forneceu, eu diria que se o seu nome de classe é uma abreviatura (ou tem abreviações como "DomUtil"), então chame seu pacote de "qualquer.WhateverUtil" (ou Utils se houver mais de um utilitário em seu pacote ) Caso contrário, se tiver um nome completo em vez de uma abreviatura, chame-o de "qualquer.Quaisquer utilidades".

Depende muito de você, mas contanto que os programadores saibam do que você está falando, você está pronto para partir. Se você está fazendo isso profissionalmente como um trabalho para alguém, pergunte quais são seus padrões de codificação antes de seguir meu conselho. Sempre siga os padrões da loja, não importa o que aconteça, pois isso o ajudará a manter seu emprego. :-)

— KSwift87
fonte