Convenção desenvolvedor/Convenção código/Java

Convenção desenvolvedor/Convenção código/Java 1.1 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:17 GMT

Linha 1

<<TableOfContents>>

Linha 2

Linha 3

TODO:9 exceto 9.2

Linha 1

~~New~~

Convenção desenvolvedor/Convenção código/Java 1.2 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:17 GMT

Linha 4

TODO:9 exceto 9.2

Convenção desenvolvedor/Convenção código/Java 1.3 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:17 GMT

Linha 3

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.

Linha 3

~~TODO:9 exceto 9.2~~

Convenção desenvolvedor/Convenção código/Java 1.4 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:17 GMT

Linha 3

<<TableOfContents>>

==Convenções de nomenclatura==

Linha 6

===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:

}

Deve-se substituir o termo <projeto> pelo nome do macro-projeto em questão:

* framework: código principal do framework;

* component: componentes opcionais;

* wizard: plugin do framework no Eclipse;

* sample: aplicações de exemplo.

Analogamente, substitui-se o termo <componente> pelo nome do componente a ser referido e que esteja contido no macro-projeto. Seguem alguns exemplos de nomes de componentes:

* core, util, web, persistence, view;

* authorization, mail, report, security;

* main, help, util;

* auction5, escola.

Convenção desenvolvedor/Convenção código/Java 1.5 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:17 GMT

Linha 15

* framework: código principal do framework;

* **framework:** código principal do framework;

Linha 16

* component: componentes opcionais;

* **component:** componentes opcionais;

Linha 17

* wizard: plugin do framework no Eclipse;

* **wizard:** plugin do framework no Eclipse;

Linha 18

* sample: aplicações de exemplo.

* **sample:** aplicações de exemplo.

Linha 26

* main, help, util;

* auction5, escola.

* main, help, util;

* auction5, escola.

Veja na tabela a seguir alguns exemplos de nomes de pacotes criados segundo a regra acima com diversos projetos e componentes:

Convenção desenvolvedor/Convenção código/Java 1.6 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:17 GMT

Linha 29

Veja na tabela a seguir alguns exemplos de nomes de pacotes criados segundo a regra acima com diversos projetos e componentes:

border="1"|= Projeto !! Componente !! Nome do pacote raiz|

Convenção desenvolvedor/Convenção código/Java 1.7 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:17 GMT

Linha 31

| Framework | Core | br.gov.framework.demoiselle.core

Linha 32

Linha 33

| | Util | br.gov.framework.demoiselle.util

Linha 34

Linha 35

| | Web | br.gov.framework.demoiselle.web

Linha 36

Linha 37

| | Persistence | br.gov.framework.demoiselle.persistence

Linha 38

Linha 39

| | View | br.gov.framework.demoiselle.view

Linha 31

Convenção desenvolvedor/Convenção código/Java 1.8 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:18 GMT

Linha 31

| Framework | Core | br.gov.framework.demoiselle.core

| rowspan=5 | Framework | Core | br.gov.framework.demoiselle.core

Linha 33

| | Util | br.gov.framework.demoiselle.util

| Util | br.gov.framework.demoiselle.util

Linha 35

| | Web | br.gov.framework.demoiselle.web

| Web | br.gov.framework.demoiselle.web

Linha 37

| | Persistence | br.gov.framework.demoiselle.persistence

| Persistence | br.gov.framework.demoiselle.persistence

Linha 39

| | View | br.gov.framework.demoiselle.view

| View | br.gov.framework.demoiselle.view

Convenção desenvolvedor/Convenção código/Java 1.9 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:18 GMT

Linha 41

| View | br.gov.framework.demoiselle.view

| rowspan=9 | Component | Authorization | br.gov.component.demoiselle.authorization

| Environment | br.gov.component.demoiselle.environment

| Hibernate Filter | br.gov.component.demoiselle.hibernate.filter

| JSF UI | br.gov.component.demoiselle.jsf

| Mail | br.gov.component.demoiselle.mail

| Report | br.gov.component.demoiselle.report

| Scheduler | br.gov.component.demoiselle.scheduler

| Security | br.gov.component.demoiselle.security

| Security Catalina | br.gov.component.demoiselle.security.catalina

Convenção desenvolvedor/Convenção código/Java 2.0 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:18 GMT

Linha 59

| Security Catalina | br.gov.component.demoiselle.security.catalina

| rowspan=3 | Wizard | Main | br.gov.wizard.demoiselle.main

| Help | br.gov.wizard.demoiselle.help

| Util | br.gov.wizard.demoiselle.util

| rowspan=2 | Sample | Auction5 | br.gov.sample.demoiselle.auction5

| Escola | br.gov.sample.demoiselle.escola

Convenção desenvolvedor/Convenção código/Java 2.1 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:18 GMT

Linha 29

}

Linha 29

~~border="1"|= Projeto !! Componente !! Nome do pacote raiz|~~

Linha 31

Tendo definido o pacote raiz do componente, é preciso definir subpacotes nele os quais abrigarão as classes, interfaces, aspectos e outros artefatos relacionados.

Linha 31

~~| rowspan=5 | Framework | Core | br.gov.framework.demoiselle.core~~

Linha 33

**a)Exemplos de nomes de artefatos**

Linha 33

~~| Util | br.gov.framework.demoiselle.util~~

Linha 35

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

Linha 35

~~| Web | br.gov.framework.demoiselle.web~~

Linha 37

}

Linha 38

Linha 39

}

Linha 37

~~| Persistence | br.gov.framework.demoiselle.persistence~~

Linha 41

**Demoiselle Component**

Linha 42

Linha 43

}

Linha 39

~~| View | br.gov.framework.demoiselle.view~~

Linha 45

}

Linha 46

Linha 47

}

Linha 41

~~| rowspan=9 | Component | Authorization | br.gov.component.demoiselle.authorization~~

Linha 42

Linha 43

~~| Environment | br.gov.component.demoiselle.environment~~

Linha 44

Linha 45

~~| Hibernate Filter | br.gov.component.demoiselle.hibernate.filter~~

Linha 46

Linha 47

~~| JSF UI | br.gov.component.demoiselle.jsf~~

Linha 48

Linha 49

~~| Mail | br.gov.component.demoiselle.mail~~

Linha 50

Linha 51

~~| Report | br.gov.component.demoiselle.report~~

Linha 52

Linha 53

~~| Scheduler | br.gov.component.demoiselle.scheduler~~

Linha 54

Linha 55

~~| Security | br.gov.component.demoiselle.security~~

Linha 56

Linha 57

~~| Security Catalina | br.gov.component.demoiselle.security.catalina~~

Linha 58

Linha 59

~~| rowspan=3 | Wizard | Main | br.gov.wizard.demoiselle.main~~

Linha 60

Linha 61

~~| Help | br.gov.wizard.demoiselle.help~~

Linha 62

Linha 63

~~| Util | br.gov.wizard.demoiselle.util~~

Linha 64

Linha 65

~~| rowspan=2 | Sample | Auction5 | br.gov.sample.demoiselle.auction5~~

Linha 66

Linha 67

~~| Escola | br.gov.sample.demoiselle.escola~~

Convenção desenvolvedor/Convenção código/Java 2.2 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:18 GMT

Linha 41

}

Linha 41

~~**Demoiselle Component**~~

Convenção desenvolvedor/Convenção código/Java 2.3 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:18 GMT

Linha 49

}

===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.

**a)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:

Convenção desenvolvedor/Convenção código/Java 2.4 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:18 GMT

Linha 52

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.

Linha 54

Linha 62

Linha 64

Linha 67

{| border="1"

}

Convenção desenvolvedor/Convenção código/Java 2.5 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:18 GMT

Linha 33

Tendo definido o pacote raiz do componente, é preciso definir subpacotes nele os quais abrigarão as classes, interfaces, aspectos e outros artefatos relacionados.

Linha 62

* ImageFileReader, WebMessageAction, JDBCTransactionResource.

Linha 68

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

{| border="1"

}

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.

**b)Sufixos da arquitetura de referência**

{| border="1"

}

**c)Outros sufixos possíveis**

Convenção desenvolvedor/Convenção código/Java 2.6 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:18 GMT

Linha 86

}

===Nomenclatura de interfaces===

As interfaces obecedem a mesma regra de nomenclatura das classes, porém elas devem conter a letra "I" como prefixo. Seguem alguns exemplos de interfaces:

* IAction, IPojo, IFactory, IDAO, IFacade, IMessage, IReport;

* IBusinessController, ITransactionResource, ISchedulerAction;

* IJNDIMailLookup, ISchedulerActionManager.

===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:

}

Convenção desenvolvedor/Convenção código/Java 2.7 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:19 GMT

Linha 115

}

===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:

* Injection, Factory, Config, Description, Report, Scheduler;

* ConfigKey, RequiredRole, EqualsField, OIDExtension;

* DefaultPersistenceUnit, ICPBrasilExtension.

===Nomenclatura de aspectos===

Os aspectos obecedem a mesma regra de nomenclatura das classes, porém devem conter o sufixo "Aspect". Seguem alguns exemplos de aspectos:

* InjectionAspect;

* PojoExtensionAspect, MethodAuthorizationAspect;

* IViewControllerMethodAuthorizationAspect, IFacadeMethodAuthorizationAspect, IDAOMethodAuthorizationAspect, IBusinessControllerMethodAuthorizationAspect.

===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:

}

Convenção desenvolvedor/Convenção código/Java 2.8 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:19 GMT

Linha 134

{| border="1"

}

create()

end()

execute()

init()

}

buildObject()

beginTransaction()

saveCookie()

sendEmail()

}

calculateFirstResult()

fillQueryNamedParameters()

}

createWithLazyCreateProxy()

findByExample()

flushAndClear()

saveOrUpdate()

}

getMaxPages()

getEntityManager()

setResponse()

setSecurityContext()

setWrappedData()

}

hasResource()

isEmpty()

isOpen()

isRowAvailable()

isUserInRole()

}

requestInitialized()

}

Convenção desenvolvedor/Convenção código/Java 2.9 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:00:19 GMT

Linha 34

**a)Exemplos de nomes de artefatos**

====**a)Exemplos de nomes de artefatos**====

Linha 63

**a)Sufixos de padrões de projeto**

====**a)Sufixos de padrões de projeto**====

Linha 75

**b)Sufixos da arquitetura de referência**

====**b)Sufixos da arquitetura de referência**====

Linha 81

**c)Outros sufixos possíveis**

====**c)Outros sufixos possíveis**====

Linha 136

create()

Linha 137

end()

Linha 138

execute()

Linha 139

init()

Linha 141

buildObject()

Linha 143

saveCookie()

Linha 146

calculateFirstResult()

Linha 147

fillQueryNamedParameters()

Linha 149

createWithLazyCreateProxy()

Linha 150

findByExample()

Linha 151

flushAndClear()

Linha 154

getMaxPages()

Linha 155

getEntityManager()

Linha 156

setResponse()

Linha 160

hasResource()

Linha 161

isEmpty()

Linha 162

isOpen()

Linha 163

isRowAvailable()