Convenções de nomenclatura #

Convenções de nomenclatura tornam os programas mais compreensíveis ao fazer com que a sua leitura seja facilitada. Elas também fornecem informação do funcionamento de um identificador – por exemplo, se este trata-se de uma constante, pacote ou classe – o qual pode ser muito útil para o entendimento do código.

Nomenclatura de pacotes #

A estrutura de pacotes dos projetos é muito importante pois, além de interferir no próprio código fonte, ela define grupo e nome no repositório Maven, nome do arquivo a ser construído (build), entre outras coisas. A estrutura de pacote é a assinatura dos componentes. No Framework Demoiselle o nome dos pacotes é definido a partir de uma estrutura raiz a qual segue o modelo abaixo:

br.gov.frameworkdemoiselle.<nome_componente ou funcionalidade>

Deve-se substituir <nome_componente ou funcionalidade> pelo nome do componente a ser referido ou funcionalidade quando for codigo do Core ou Extensões.

Especialmente, existe o pacote internal que deve ser usado para identificar o conjunto de classes que são de uso interno. Classes de uso interno poderão ser modificadas conforme a necessidade do projeto, sem a preocupação com quebra de versão.

Veja na tabela a seguir alguns exemplos de nomes de pacotes criados segundo a regra acima :

Tendo definido o pacote raiz, é preciso definir subpacotes nele os quais abrigarão as classes, interfaces, anotações e outros artefatos relacionados.

A estrutura para os outros projetos segue o seguinte formato:

br.gov.frameworkdemoiselle.<Projeto>.<SubProjeto>

Exemplos de nomes de artefatos #

Eis alguns exemplos de nomes qualificados de artefatos existentes nos projetos:

Demoiselle Core

br.gov.frameworkdemoiselle.internal.proxy.Slf4jLoggerProxy
br.gov.frameworkdemoiselle.annotation.ViewScoped
br.gov.frameworkdemoiselle.util.Strings

Demoiselle Extensions

br.gov.frameworkdemoiselle.internal.proxy.HttpSessionProxy
br.gov.frameworkdemoiselle.template.PageBean

Demoiselle Components

br.gov.frameworkdemoiselle.mail.util.MailUtil

Demoiselle Tools

br.gov.frameworkdemoiselle.tools.nimble.gui.GenericFrame

Demoiselle Sample

br.gov.frameworkdemoiselle.sample.estacionamento.domain.Automovel

Nomenclatura de classes #

O nome de uma classe é sempre um substantivo, e é composto por uma mistura de letras maiúsculas e minúsculas. A primeira letra de cada palavra que compõe o nome da classe deve ser maiúscula.

Tente manter o nome das classes simples e descritivo. Utilize palavras inteiras e evite acrônimos e abreviações a menos que estes sejam mais comumente usados do que a forma completa (e.g. URL ou HTML).

Eis alguns exemplos de nomes de classes válidos segundo as regras anteriores:

• Auction, Professor, Constant, Cookie, Email, Connection;
• ContaCorrente, PapelUsuario, ImageLoader, TransactionResource;
• ImageFileReader, WebMessageAction, JDBCTransactionResource.

Sufixos de padrões de projeto #

As classes que implementam algum padrão de projeto (design pattern) devem utilizar em sua nomenclatura um sufixo determinado que indique o pattern em questão.

Na tabela a seguir estão listados alguns sufixos para padrões encontrados no código fonte do framework e componentes:

Classes que representam os padrões JavaBeans ou POJO (Plain Old Java Object) simplesmente não possuem sufixo que os designem como tal. Eis alguns exemplos: Aluno, Disciplina, Usuario, Auction, Bid, Order.

Sufixos da arquitetura de referência #

Outros sufixos possíveis #

Nomenclatura de enumerações #

As enumerações (enums) também obedecem às regras de nomenclatura das classes, mas às vezes podem conter o sufixo "Type" ou o prefixo "Tipo" em aplicações de referência. Eis alguns exemplos de enumerações:

• Status, Severity, Color, Sexo, Turno, Resultado;
• InfoMessage, TransactionType, CustomType, TipoAcesso.

Internamente os itens da enumeração devem ser nomeados segundo a regra para a nomenclatura de constantes (a ser definida nas seções seguintes).

Seguem exemplos de implementações de enumerações:

public enum TransactionType {

       JTA, LOCAL;

}

public enum ConfigType {

       SYSTEM,
       XML,
       PROPERTIES;

}

Nomenclatura de anotações #

As anotações (annotations), declaradas através da cláusula @interface, serão usadas em declarações de outras classes através do operador @NomeAnotação, e por isso devem possuir nomenclatura de fácil assimilação. Seguem alguns exemplos de anotações:

• Configuration, Description, Report, Scheduler;
• ConfigKey, RequiredRole, EqualsField, OIDExtension;
• DefaultPersistenceUnit, ICPBrasilExtension.

Nomenclatura de métodos #

Os métodos deverão ser nomeados com verbos, através de uma mistura de letras minúsculas e maiúsculas. Em princípio todas as letras que compõem o nome devem ser mantidas em minúsculo, com exceção da primeira letra de cada palavra composta a partir da segunda palavra. Além disso, no caso de siglas ou acrônimos (ex: UID, HQL, JPQL), suas respectivas letras devem ficar todas em maiúsculo exceto se estiverem na primeira palavra do nome.

Tipicamente os verbos serão escritos no tempo infinitivo, porém existem casos especiais em que esse padrão não é usado. Veja na tabela a seguir as diversas formas de se nomear um verbo segundo uma classificação pela sua funcionalidade.

Nomenclatura de variáveis #

O nome de uma variável, se formado por uma única palavra, deve ser declarado inteiramente em minúsculo. No caso de palavras compostas, apenas a primeira letra de cada palavra, a partir da segunda palavra, deve estar em maiúsculo. Em se tratando de siglas ou acrônimos (ex: CPF, HTML, URL), suas respectivas letras devem ficar todas em maiúsculo exceto se estiverem na primeira palavra.

Os nomes de variáveis e identificadores em geral no Java não podem começar com caracteres especiais e nem com números e, apesar de válido, devem-se evitar os caracteres underscore "_" e cifrão "$".

Além disso, o nome das variáveis devem ser pequenos e de fácil entendimento. A escolha do nome de uma variável deve ser mnemônica, ou seja, projetado para indicar a um observador casual a intenção de seu uso.

Todavia, variáveis cujo nome tenha apenas um caractere deve ser evitado, com exceção de variáveis temporárias utilizadas em laços de repetição, onde geralmente usamos i, j ou k.

Quando a variável tiver a função de representar uma coleção de objetos, tais como array, lista ou conjunto, deixe o seu nome no plural (ex: nomes, values).

Seguem alguns exemplos de nomes de variáveis segundo as regras acima:

• name, page, list, instance, log, context, loader, object, clazz;
• rowIndex, className, parameterTypes, urlExists, possuiCPF;
• totalNumRows, actionClassName, serialVersionUID.

Nomenclatura de constantes #

O nome das constantes sempre deve ser declarado em letras maiúsculas, separadas por underscores “_” no caso de existirem múltiplas palavras.

Eis alguns exemplos de declarações de constantes segundo as regras acima:

public static final String PROFESSOR = "role_professor";

public static final String TURMA_VISUALIZAR = "turma_visualizar";

public static final String FRAMEWORK_CONFIGURATOR_FILE = "demoiselle.properties";

public static final String WEB_REDIRECT_SERVLET_URL_PATTERN = "/redirect";

private static final long MILISSEGUNDOS_EM_30_ANOS = 933120000000l;

private static final String[] NOMES_MULHERES = {"Ana", "Beatriz", "Camila"};