Orientações técnicas/Práticas de programação

Orientações técnicas/Práticas de programação 1.1 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:01:05 GMT

Linha 1

<<TableOfContents>>

Linha 2

Linha 3

TODO: cap 11 do convecao de codigo demoiselle

Linha 4

Linha 1

~~New~~

Orientações técnicas/Práticas de programação 1.2 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:01:05 GMT

Linha 3

== Considerações gerais ==

Linha 3

~~TODO: cap 11 do convecao de codigo demoiselle~~

Linha 5

O objetivo deste documento é o de fornecer aos desenvolvedores do Demoiselle algumas orientações a serem seguidas em Java visando as melhores práticas de programação. Tais práticas devem ser seguidas a fim de se garantir um bom nível de qualidade para os códigos, em ambos os termos de desempenho e de manutenibilidade destes.

=== Tamanho razoável dos códigos fontes ===

Se um arquivo de fonte do Java passa a ser grande, mais do que 500 linhas, tente reduzir o seu tamanho através da refatoração de códigos duplicados em um único método ou pela externalização do código para uma outra classe.

=== Granularidade dos métodos ===

Um número razoável de linhas para um método depende de sua complexidade. Um método formado por instruções sequenciais pode ser consideravelmente maior do que um método complexo contendo laços e estruturas condicionais. Se o código sequencial é repetitivo, tal como na inicialização índice a índice de um array, ele pode ser tão longo quanto for necessário. Porém, deve existir uma maneira mais elegante de construi-lo.

Um método deve preferivelmente fazer apenas uma coisa, e o seu nome descreve tal funcionalidade. Se ele efetua diversas tarefas, tenha certeza de que estas estejam refletidas no nome do método. Se isso levar a um nome longo e complicado, é aconselhável rever a estrutura interna do seu código. Por exemplo, se você tiver um método com o nome inicializarPaginaDeGestaoELerListaContas(), provavelmente será possível dividi-lo em dois métodos: inicializarPaginaDeGestao() e lerListaContas().

=== Utilização dos tipos float e double ===

Não utilize os tipos de dados primitivos float e double para cálculos onde a precisão dos números decimais é importante. Por causa da representação interna dos tipos de dados float e double [10], o cálculo usando números de pontos flutuantes não podem ser considerados precisos. Dada esta recomendação da IBM [11], não use os tipos simples float ou double para efetuar cálculos de números decimais onde a precisão é importante. Se necessário, a classe BigDecimal pode ser usada no lugar destes tipos.

== Fornecendo acesso a variáveis de instância e de classe ==

Não torne uma variável de instância ou de classe pública sem uma boa razão. Frequentemente variáveis de instância não precisam ser explicitamente atribuídas ou obtidas, isso ocorre automaticamente através de chamadas a métodos.

Um exemplo apropriado de variáveis de instância públicas é o caso onde a classe é essencialmente uma estrutura de dados, sem comportamento algum. Em outras palavras, se você tivesse usado uma estrutura ao invés de uma classe (se o Java suportasse "struct"), então é apropriado tornar públicas as variáveis de instância da classe.

== Referenciando variáveis e métodos de classe ==

Evite usar um objeto para acessar uma variável ou método de classe, isto é, caso possuam o modificador static. Ao invés disso use o nome da classe diretamente. Seguem alguns exemplos:

}

== Constantes ==

Constantes numéricas (literais) não deverão ser codificadas diretamente, exceto para os casos -1, 0 e 1, os quais podem aparecer em um laço “for” como valores para um contador.

== Atribuições de valores ==

Evite atribuir a diversas variáveis um mesmo valor em uma única instrução. Isso dificulta a leitura. Exemplo:

}

Não use operador de atribuição em lugares onde podem ser confundidos facilmente com o operador de igualdade. Por exemplo, considere o caso abaixo:

}

o código deveria ser escrito dessa outra forma:

}

Além disso, não use atribuições embutidas na tentativa de se melhorar o desempenho em tempo de execução. Isso é trabalho para o compilador e, além do mais, raramente auxilia de verdade. Por exemplo:

}

Isso deve ser escrito dessa forma:

}

== Importação de pacotes ==

Demoiselle - Convenções de Codificação

Para manter uma boa legibilidade do código, mantenha apenas importações de classes ou outros artefatos Java que estejam de fato sendo referenciados no arquivo em questão. Além disso, recomenda-se não utilizar o nome qualificado de classes internamente no código, optando pelo mecanismo de importação da linguagem Java (cláusula "import").

Procure utilizar o símbolo "*" durante a importação dos elementos de um pacote somente nos casos em que aparecerem mais de 10 artefatos a serem importados, preferindo a importação individual.

11.7.Utilização de interfaces ao invés de implementações nas declarações

Onde for possível (quando o objeto que se quer usar implementa uma interface), é melhor declarar a variável como sendo do tipo da interface ao invés do tipo da classe da implementação.

Isso é particularmente aplicável às classes de coleções. Por exemplo, é melhor escrever o código abaixo:

List alunos = new ArrayList(); // PREFERIDO

ao invés disso:

ArrayList alunos = new ArrayList(); // EVITAR

Desta forma é possível alterar posteriormente o tipo de dados real usado com o mínimo de impacto no resto do código (por exemplo, substituir ArrayList por LinkedList).

11.8.Utilização do modificador final

Quando uma variável de classe ou de instância não é modificada em momento algum do ciclo de vida do objeto, declare esta variável com o modificador "final".

Os parâmetros de um método e as variáveis locais também podem ser declarados com o "final".

11.9.Redefinição ou sobrecarga de métodos

Um método redefinido ou ou sobrecarregado (overloaded) deve oferecer a mesma funcionalidade presente na classe ancestral. Tome cuidado para não alterar o significado de um método ao redefini-lo na classe derivada.

11.10.Liberação de recursos associados a uma classe

Demoiselle - Convenções de Codificação de execução desta. Além disso, a execução deste método depende do algoritmo do garbage collector em questão, sendo desta maneira dependente da implementação da

máquina virtual usada (ex: Sun, IBM, BEA).

11.11.Cautela na utilização do método equals()

Preste muita atenção ao comportamento do método equals(). A implementação padrão dele na classe Object simplesmente compara a identidade dos objetos com o operador de igualdade "==". Algumas classes redefinem este método fornecendo-o um significado de igualdade, tal como a classe String, na qual o equals() realiza a comparação de duas strings caracter a caracter. Por outro lado, outras classes mantêm o comportamento original do método.

Segue um exemplo com a classe String:

String s1 = new String("Texto"); String s2 = new String("Texto");

(s1 == s2); // retorna false s1.equals(s2); // retorna true

Ao utilizar a classe StringBuffer o resultado é outro:

StringBuffer sb1 = new StringBuffer("Texto"); StringBuffer sb2 = new StringBuffer("Texto");

(sb1 == sb2); // retorna false sb1.equals(sb2); // retorna false

11.12.Redefinição do método hashCode()

Sempre redefina o método hashCode() de uma classe se o método equals() dela tenha sido reimplementado. O método hashCode() é usado pelas aplicações que fazem uso de tabelas de hash, tal como nas classes Hashtable ou HashMap, para armazenar os objetos.

Para ser capaz de encontrar os objetos armazenados em um contêiner baseado em tabelas de hash, e por consequência usando o método hashCode(), é essencial que esta regra seja respeitada:

Do mesmo modo, o código hash de um objeto não deve ser alterado durante o seu ciclo de vida, e desta forma no seu cálculo não podem ser usadas informações prováveis de serem modificadas. Sendo assim, recomenda-se que apenas atributos ditos "final" do objeto sejam usados ao se calcular o seu código hash.

Se objeto1.equals(objeto2), então objeto1.hashCode() == objeto2.hashCode().

11.13.Escolha da implementação de listas e mapas

Demoiselle - Convenções de Codificação

Priorize a utilização das implementações ArrayList e HashMap sobre Vector e Hashtable a fim de obter melhor desempenho quando acesso sincronizado não for necessário.

De fato Vector e Hashtable oferecem métodos ditos "synchronized", porém eles são custosos e mais lentos de serem executados para garantir essa sincroniza ao controlar a concorrência. Na plataforma Java o Collection Framework traz as classes ArrayList e HashMap, cujas funcionalidades são as mesmas desempenhadas respectivamente por Vector e Hashtable, com a ressalva de que seus métodos não são sincronizados.

11.14.Escrevendo o tratamento de exceções

Nunca deixe vazio um bloco "catch" em instruções do tipo "try-catch", mesmo em fase dedesenvolvimento. O mínimo que se pode fazer é deixar um comentário explicando porque nada foi feito durante o "catch" ou um marcador (ex: "TODO") para lembrar que aquela parte do código não foi ainda finalizada.

Geralmente utilizamos um mecanismo de logging (ex: Log4J), onde pode-se definir um nível (ex: DEBUG, INFO, ERROR) para uma mensagem enviada de dentro do "try-catch".

No bloco "finally" do "try-catch", evite levantar outras exceções ou retornar prematuramente. Como por definição o bloco "finally" é executado em qualquer situação, ele o será no caso de um bloco "catch" ter levantado uma exceção. Se o próprio bloco "finally" levantar uma exceção, esta provavelmente irá esconder uma exceção levantada anteriormente no "catch". Do mesmo modo, se houver uma instrução "return" no bloco "finally", o método irá finalizar normalmente pelo "return" mesmo se o bloco "catch" tiver levantado uma exceção.

11.15.Práticas gerais na codificação a)Parênteses

O uso livre de parênteses é geralmente considerado uma boa prática, principalmente em expressões que utilizam vários operadores com o objetivo de se evitar problemas de precedência. Mesmo que a precedência do operador parece clara para você, ela pode não ser para outros – não assuma que outros programadores conheçam precedência tão bem quanto você. Seguem exemplos:

if(a==b&&c==d) //EVITAR! if ((a == b) && (c == d)) // PREFERIDO

b)Retorno de valores

Tente fazer com que a estrutura de seu programa reflita a sua real intenção. Por exemplo, o código a seguir:

if (expressaoLogica) { return TRUE;

Demoiselle - Convenções de Codificação

} else { return FALSE;

}

deveria ser escrito desta outra forma:

return expressaoLogica;

Similarmente, este outro código

if (condição) { return x;

} return y;

deveria ser escrito assim:

return (condição ? x : y);

c)Operador ternário

Se uma expressão contendo um operador binário aparecer antes do sinal "?" do operador ternário, ela deve estar entre parênteses. Segue um exemplo:

(x >= 0) ? x : -x;

d)Comentários especiais

Existem tags especiais de tarefas, ditas Task Tags, que servem justamente para indicar, através de comentários simples, que o código que se segue necessita de alguma correção ou conclusão.

• TODO: para marcar que há uma tarefa pendente de início ou conclusão no código fonte abaixo do comentário;

• FIXME: para marcar que há algo incoerente no código e que precisa de correção urgente;

• XXX: para marcar que existe código fora dos padrões, não elegante ou sem garantia de desempenho, porém que funciona.

Essas tags geralmente são interpretadas pelo ambiente de desenvolvimento e suas indicações aparecem em visões e janelas apropriadas para que o desenvolvedor possa gerenciar o respectivo código defeituoso ou incompleto.

Eis alguns exemplos de utilização dessas tags:

// TODO: Terminar a codificação da leitura do arquivo boolean leuArquivo = Classe.abrirArquivo("teste.properties");

// FIXME: Verificar erro durante execução do método String resultado = Classe.metodoQualquer(100);

Orientações técnicas/Práticas de programação 1.3 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:01:05 GMT

Linha 60

== Importação de pacotes ==

~~Demoiselle - Convenções de Codificação~~

== Importação de pacotes ==

Linha 61

Linha 63

Linha 64

~~11.7.~~Utilização de interfaces ao invés de implementações nas declarações

== Utilização de interfaces ao invés de implementações nas declarações ==

Linha 65

Linha 67

Linha 69

Linha 70

}

Linha 71

Linha 66

~~List alunos = new ArrayList(); // PREFERIDO~~

Linha 73

}

Linha 74

Linha 68

~~ArrayList alunos = new ArrayList(); // EVITAR~~

Linha 76

Linha 70

Linha 77

~~11.8.~~Utilização do modificador final

== Utilização do modificador final ==

Linha 78

Linha 80

Linha 82

Linha 73

Linha 83

~~11.9.~~Redefinição ou sobrecarga de métodos

== Redefinição ou sobrecarga de métodos ==

Linha 84

Linha 86

Linha 75

Linha 87

~~11.10.~~Liberação de recursos associados a uma classe

== Liberação de recursos associados a uma classe ==

Linha 76

Linha 88

Linha 77

Linha 89

Não confie ao método finalize() de uma classe a liberação de recursos relacionados a uma instância dela. Este método, presente na classe Object, é invocado pela JVM um pouco antes do garbage collector liberar o espaço de memória alocado para a instância. Porém, não há garantia do momento exato da execução do método finalize(), por exemplo, ele pode ser chamado somente na finalização da aplicação e prender os recursos por todo o período de execução desta. Além disso, a execução deste método depende do algoritmo do garbage collector em questão, sendo desta maneira dependente da implementação da máquina virtual usada (ex: Sun, IBM, BEA).

Linha 78

Linha 90

Linha 79

Linha 91

~~máq~~uina ~~virtu~~al usada ~~(ex:~~ Su~~n, IBM, BEA~~).

== Cautela na utilização do método equals() ==

Linha 80

Linha 92

~~11.11.Cautela na utilização do método equals()~~

Linha 94

Linha 96

Linha 97

}

Linha 98

Linha 83

~~String s1 = new String("Texto"); String s2 = new String("Texto");~~

Linha 84

~~(s1 == s2); // retorna false s1.equals(s2); // retorna true~~

Linha 100

}

Linha 101

Linha 102

== Redefinição do método hashCode() ==

Linha 103

Linha 86

~~StringBuffer sb1 = new StringBuffer("Texto"); StringBuffer sb2 = new StringBuffer("Texto");~~

Linha 87

~~(sb1 == sb2); // retorna false sb1.equals(sb2); // retorna false~~

Linha 88

~~11.12.Redefinição do método hashCode()~~

Linha 105

Linha 107

}

Linha 111

Linha 112

== Escolha da implementação de listas e mapas ==

Linha 113

Linha 92

~~Se objeto1.equals(objeto2), então objeto1.hashCode() == objeto2.hashCode().~~

Linha 93

Linha 94

~~11.13.Escolha da implementação de listas e mapas~~

Linha 95

~~Demoiselle - Convenções de Codificação~~

Linha 115

Linha 117

Linha 98

Linha 118

~~11.14.~~Escrevendo o tratamento de exceções

== Escrevendo o tratamento de exceções ==

Linha 119

Linha 121

Linha 123

Linha 125

Linha 102

Linha 126

~~11.15.~~Práticas gerais na codificação ~~a)Parênteses~~

== Práticas gerais na codificação ==

Linha 127

Linha 128

=== Parênteses ===

Linha 129

Linha 131

Linha 132

}

Linha 133

Linha 134

=== Retorno de valores ===

Linha 135

Linha 104

~~if(a==b&&c==d) //EVITAR! if ((a == b) && (c == d)) // PREFERIDO~~

Linha 105

~~b)Retorno de valores~~

Linha 137

Linha 107

~~if (expressaoLogica) { return TRUE;~~

Linha 108

Linha 109

~~Demoiselle - Convenções de Codificação~~

Linha 110

~~} else { return FALSE;~~

Linha 139

Linha 141

Linha 142

}

Linha 143

Linha 113

~~return expressaoLogica;~~

Linha 145

}

Linha 146

Linha 115

~~if (condição) { return x;~~

Linha 116

~~} return y;~~

Linha 148

Linha 149

}

Linha 150

Linha 151

=== Operador ternário ===

Linha 152

Linha 118

~~return (condição ? x : y);~~

Linha 119

~~c)Operador ternário~~

Linha 154

Linha 155

}

Linha 156

Linha 157

=== Comentários especiais ===

Linha 158

Linha 121

~~(x >= 0) ? x : -x;~~

Linha 122

~~d)Comentários especiais~~

Linha 160

Linha 124

Linha 161

• TODO: para marcar que há uma tarefa pendente de início ou conclusão no código fonte abaixo do comentário;

*TODO: para marcar que há uma tarefa pendente de início ou conclusão no código fonte abaixo do comentário;

Linha 125

Linha 162

• FIXME: para marcar que há algo incoerente no código e que precisa de correção urgente;

*FIXME: para marcar que há algo incoerente no código e que precisa de correção urgente;

Linha 126

Linha 163

• XXX: para marcar que existe código fora dos padrões, não elegante ou sem garantia de desempenho, porém que funciona.

*XXX: para marcar que existe código fora dos padrões, não elegante ou sem garantia de desempenho, porém que funciona.

Linha 164

Linha 166

Linha 168

Linha 169

}

Linha 129

~~// TODO: Terminar a codificação da leitura do arquivo boolean leuArquivo = Classe.abrirArquivo("teste.properties");~~

Linha 130

~~// FIXME: Verificar erro durante execução do método String resultado = Classe.metodoQualquer(100);~~

Linha 131

Orientações técnicas/Práticas de programação 1.4 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:01:05 GMT

Linha 170

}

Orientações técnicas/Práticas de programação 1.5 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:01:05 GMT

Orientações técnicas/Práticas de programação 1.6 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:01:06 GMT

Linha 171

}

Orientações técnicas/Práticas de programação 1.7 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:01:06 GMT

Linha 161

*TODO: para marcar que há uma tarefa pendente de início ou conclusão no código fonte abaixo do comentário;

* **TODO**: para marcar que há uma tarefa pendente de início ou conclusão no código fonte abaixo do comentário;

Linha 162

*FIXME: para marcar que há algo incoerente no código e que precisa de correção urgente;

* **FIXME**: para marcar que há algo incoerente no código e que precisa de correção urgente;

Linha 163

*XXX: para marcar que existe código fora dos padrões, não elegante ou sem garantia de desempenho, porém que funciona.

* **XXX**: para marcar que existe código fora dos padrões, não elegante ou sem garantia de desempenho, porém que funciona.

Orientações técnicas/Práticas de programação 1.8 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:01:06 GMT

Orientações técnicas/Práticas de programação 1.9 (Edição mínima)

Test Test — Wed, 09 Jan 2013 20:01:06 GMT

Orientações técnicas/Práticas de programação 2.0

Test Test — Fri, 05 Apr 2013 22:25:42 GMT

Linha 15

Linha 26

Linha 33

{{{

Linha 34

metodoQualquer(); // OK

Linha 35

Classe.metodoQualquer(); // OK

Linha 36

objeto.metodoQualquer(); // EVITAR!

Linha 37

}}}

Linha 31

}

Linha 39

Linha 48

{{{

Linha 49

fooBar.fChar = barFoo.lchar = ‘c’; // EVITAR!

Linha 50

}}}

Linha 41

}

Linha 52

Linha 55

{{{

if (c++ = d++) { ...

Linha 58

}}}

Linha 62

{{{

if ((c++ = d++) != 0) { ...

Linha 65

}}}

Linha 67

Linha 70

{{{

Linha 71

d = (a = b + c) + r; // EVITAR!

Linha 72

}}}

Linha 53

}

Linha 56

}

Linha 76

{{{

a = b + c; d = a + r;

}}}

Linha 84

Linha 91

Linha 94

{{{

Linha 95

List alunos = new ArrayList(); // PREFERIDO

Linha 96

}}}

Linha 70

}

Linha 99

{{{

Linha 100

ArrayList alunos = new ArrayList(); // EVITAR

Linha 101

}}}

Linha 73

}

Linha 109

Linha 124

Linha 127

{{{

Linha 128

String s1 = new String("Texto");

Linha 129

String s2 = new String("Texto");

Linha 130

Linha 131

(s1 == s2); // retorna false

Linha 132

s1.equals(s2); // retorna true

Linha 133

}}}

Linha 97

}

Linha 135

Linha 100

}

Linha 138

{{{

StringBuffer sb1 = new StringBuffer("Texto");

StringBuffer sb2 = new StringBuffer("Texto");

(sb1 == sb2); // retorna false

sb1.equals(sb2); // retorna false

}}}

Linha 150

Linha 153

{{{

Linha 154

Se objeto1.equals(objeto2), então objeto1.hashCode() == objeto2.hashCode().

Linha 155

}}}

Linha 108

}

Linha 163

Linha 170

Linha 173

Linha 177

=== Parênteses ===

Linha 128

~~=== Parênteses ===~~

Linha 181

{{{

Linha 182

if (a == b && c == d) // EVITAR!

Linha 183

Linha 184

if ((a == b) && (c == d)) // PREFERIDO

Linha 185

}}}

Linha 132

}

Linha 191

{{{

if (expressaoLogica) {

return TRUE;

} else {

return FALSE;

Linha 197

}}}

Linha 199

Linha 202

{{{

Linha 203

return expressaoLogica;

Linha 204

}}}

Linha 142

}

Linha 206

Linha 145

}

Linha 209

{{{

if (condição) {

return x;

}

return y;

}}}

Linha 218

{{{

Linha 219

return (condição ? x : y);

Linha 220

}}}

Linha 149

}

Linha 226

{{{

Linha 227

(x >= 0) ? x : -x;

Linha 228

}}}

Linha 155

}

Linha 238

Linha 241

Linha 244

{{{

Linha 245

// TODO: Terminar a codificação da leitura do arquivo

Linha 246

boolean leuArquivo = Classe.abrirArquivo("teste.properties");

Linha 247

}}}

Linha 169

}

Linha 249

{{{

Linha 250

// FIXME: Verificar erro durante execução do método

Linha 251

String resultado = Classe.metodoQualquer(100);

Linha 252

}}}

Linha 171

}

Linha 172