Guia do Google para formatação de código Java

1. Introdução

Este documento descreve os padrões de codificação na linguagem de programação Java no Google. O código-fonte Java é considerado em conformidade com esses padrões se, e somente se, atender a todas as regras descritas neste documento.



Os tópicos abordados neste tutorial não são apenas sobre o lado estético da formatação de código, mas também outros tipos de convenções ou padrões de codificação. No entanto, este documento se concentra principalmente na definição de regras estritas que seguimos em todos os lugares e não fornece recomendações que podem ser implementadas incorretamente (tanto por humanos quanto por máquinas-ferramenta).

1.1 Terminologia

Ao longo deste guia, os seguintes termos são definidos:

1. O termo classe é usado para significar uma classe "regular", enumeração, interface ou tipo de anotação (@interface)
2. O termo membro da classe é usado para se referir a uma classe aninhada, campo, método ou construtor, ou seja, para todos os membros da classe de alto nível, exceto blocos de inicialização e comentários.
3. O termo comentário sempre se refere a comentários de implementação. Não usamos a frase "comentários de documentação", mas em vez disso usamos o termo "Javadoc"

O restante da terminologia será fornecido conforme necessário ao longo deste manual.

1.2 Nota do guia

Os exemplos de código neste documento não demonstram a única abordagem estilística correta para sua formatação, embora sejam usados ​​em nosso tutorial.

2. Arquivo fonte. O básico

2.1 Nome do arquivo

Um nome de arquivo de origem consiste no nome de uma classe de nível superior específica que reside nele. O nome diferencia maiúsculas de minúsculas e termina com uma extensão .java

2.2 Codificação do arquivo: UTF-8

Arquivos com código são codificados em UTF-8.

2.3 caracteres especiais

2.3.1 Caracteres de espaço

Além da seqüência de caracteres de fim de linha, o caractere de espaço ASCII horizontal (0x20) é o único caractere delimitador encontrado no arquivo de origem. Significa que:

1. Todos os outros caracteres de espaço em branco em caracteres e literais de string são escapados
2. Os caracteres de tabulação não são usados ​​para recuo

2.3.2 Sequências de escape especiais

Para cada caractere para o qual existe uma sequência de escape especial (\ b, \ t, \ n, \ f, \ r, \ ", \ 'e \\), é preferível usá-lo em vez de seu valor octal correspondente (por exemplo, \ 012 ) ou código Unicode (por exemplo, \ u000a).

2.3.3 Caracteres não ASCII

Para caracteres não ASCII, use o caractere Unicode (por exemplo, ∞) ou uma sequência de escape equivalente (por exemplo, \ u221e). A escolha é dada em favor dos símbolos que tornam o código mais compreensível e legível.

Ao usar caracteres de escape na codificação Unicode e nos casos em que são usados ​​caracteres Unicode válidos, recomendamos enfaticamente que esse código seja acompanhado de comentários explicativos.

Nunca torne seu código menos legível apenas por medo de que alguns programas não sejam capazes de processar corretamente caracteres não ASCII. Se isso acontecer, esses programas não funcionam corretamente e precisam ser corrigidos.

3. Estrutura do arquivo fonte

O arquivo de origem consiste nos seguintes elementos (na ordem mostrada):

1. Licença ou informações de direitos autorais, se houver
2. Declaração do pacote
3. Declarando importações
4. Declaração de classe

Exatamente uma linha em branco separa cada seção presente.

3.1 Licença ou informações de direitos autorais, se houver

As informações sobre licença ou direitos autorais devem ser incluídas no arquivo a que se referem.

3.2 Declaração da embalagem

O pacote é declarado sem quebra de linha. A limitação da largura da linha (Seção 4.4) não se aplica a uma declaração de pacote.

3.3 Declarações de importação

3.3.1 Curinga nas declarações de importação

O caractere * (curinga) não é usado ao declarar importações, estáticas ou não.

3.3.2 Quebra de linha

As importações são declaradas sem quebras de linha. Eles não estão sujeitos ao limite de largura de linha.

3.3.3 Ordenação e espaçamento

As importações são ordenadas da seguinte forma:

1. Todas as importações estáticas são colocadas e agrupadas em um bloco
2. Todas as importações não estáticas são colocadas em outro bloco

Se as importações estáticas e não estáticas forem declaradas, esses blocos devem ser separados por uma linha em branco. Não deve haver nenhuma outra linha em branco entre eles.



Em cada bloco, as classes importadas são listadas na ordem de classificação dos caracteres ASCII.

3.3.4 Importação estática de classes aninhadas

As importações estáticas não são usadas para classes aninhadas estáticas. Essas classes são importadas com uma declaração de importação regular.

3.4 Declaração de classe

3.4.1 Exatamente uma classe de nível superior é declarada

Cada classe de nível superior está localizada em seu próprio arquivo de origem.

3.4.2 Ordenando o conteúdo de uma aula

A ordem em que você coloca os membros e os blocos de inicialização de uma classe pode ter um grande impacto na facilidade de compreensão do seu código. De qualquer forma, não existe uma receita simples e correta para isso; classes diferentes podem organizar seu conteúdo de maneira diferente.



O importante é que cada classe tenha uma ordem lógica de conteúdo para que o programador que está lendo o código possa explicá-lo.

3.4.2.1 Código sobrecarregado não deve ser dividido

Quando uma classe tem vários construtores ou métodos com o mesmo nome, eles devem ser colocados sequencialmente, sem inserir outro código entre eles.

4. Formatação

Terminologia

O corpo de uma classe, método ou construtor é uma construção em bloco .



Observe que, de acordo com a Seção 4.8.3.1, qualquer inicializador de array também pode ser considerado uma construção de bloco.

4.1 Cintas

4.1.1 Cintas onduladas são usadas onde quer que possam ser usadas

Os colchetes são usados ​​em if, else, for, while e do-while, mesmo se o corpo da expressão estiver vazio ou contiver apenas uma linha de código.

4.1.2 Blocos não vazios: Estilo K&R

Os colchetes são colocados de acordo com o estilo de Kernighan e Ritchie ("colchetes egípcios") para blocos não vazios e estruturas de bloco (para maior clareza, decidimos adicionar um pequeno código demonstrando essas regras - nota do tradutor):

• Nenhuma quebra de linha é feita antes do parêntese de abertura:

// 
if (true) { 

// 
if (true)
{

• Uma quebra de linha é feita após o parêntese de abertura:

// 
while (true) {
  // code

// 
while (true) { // code

• Uma quebra de linha é feita antes do parêntese de fechamento:

// 
for () {
  // code
}

// 
while (true) { /* code */ }

// 
if (true) {
  /* code */ }

• Uma quebra de linha ocorre após um parêntese de fechamento apenas se esse parêntese terminar uma expressão ou corpo de um método, construtor ou classe não anônima. Uma quebra de linha não é feita após um parêntese se for seguida por outro, catch ou ponto-e-vírgula

Exemplos de regras executadas corretamente:

return () -> {
  while (condition()) {
    method();
  }
};

return new MyClass() {
  @Override public void method() {
    if (condition()) {
      try {
        something();
      } catch (ProblemException e) {
        recover();
      }
    } else if (otherCondition()) {
      somethingElse();
    } else {
      lastThing();
    }
  }
};

Algumas exceções para enumerações são fornecidas na Seção 4.8.1

4.1.3 Blocos vazios podem ser comprimidos

Um bloco vazio ou construção de bloco vazio pode seguir o estilo K&R (conforme descrito na Seção 4.1.2). Também é possível que esse bloco seja fechado imediatamente após a abertura, sem caracteres ou quebras de linha dentro {}. Esta regra não se aplica quando o bloco faz parte de uma expressão de vários blocos que contém if-else ou try-catch-finally.



Exemplos:

// 
void doNothing() {}

//  
void doNothingElse() {
}

// :       
try {
  doSomething();
} catch (Exception e) {}

4.2 Dois espaços para indentação

Cada vez que um novo bloco ou construção de bloco é aberto, o deslocamento para a direita é aumentado em dois espaços. Quando um bloco termina, o início da próxima linha de código é deslocado para o nível de deslocamento anterior. O nível de deslocamento se aplica ao bloco e aos comentários nesse bloco (consulte um exemplo na Seção 4.1.2).

4.3 Uma expressão por linha

Cada expressão termina com uma quebra de linha.

4.4 Limitando a largura da linha a 100 caracteres

O código Java é limitado a 100 caracteres na largura da linha. Um "caractere" se refere a qualquer um dos elementos Unicode. Exceto conforme descrito abaixo, cada linha que excede o limite de largura deve ser quebrada conforme explicado na Seção 4.5.



Exceções:

1. , (, URL Javadoc JSNI- )
2. package import (. 3.2 3.3)
3. ,

4.5

Quando o código que poderia estar na mesma linha é dividido em várias linhas, esse fenômeno é chamado de quebra de linha.



Não existe uma fórmula não ambígua geralmente aceita que determine exatamente como as quebras de linha devem ser feitas em cada situação. Muitas vezes, existem várias maneiras de quebrar uma linha com o mesmo trecho de código.



Normalmente, a quebra é feita para evitar o estouro da largura da linha. Mas mesmo se o código permanecer dentro da largura permitida, então, na decisão do autor, ele pode ser quebrado em uma nova linha.

Alocar um método auxiliar ou variável local pode resolver o problema de estouro de largura de linha sem quebrar o código

4.5.1 Para onde transferir

A primeira diretriz para quebras de linha diz: é preferível fazer a quebra de linha em um nível sintático superior. Além disso:



1. Quando uma linha é quebrada em uma instrução sem atribuição, a quebra é feita antes do caractere.



Esta regra também se aplica aos seguintes caracteres "semelhantes aos de operador":

• ponto de divisão "."
• dois pontos duplos do método de referência "::"
• E comercial entre parênteses genérico <T extends Foo & Bar>
• delimitador no bloco catch (FooException | BarException e)

2. Quando uma string é quebrada em uma instrução de atribuição, a quebra geralmente é feita depois do caractere, mas outra solução



é aceitável.Isso também se aplica aos dois pontos para o loop for-each.



3. O nome do método ou construtor quando a quebra de linha permanece anexado ao parêntese de abertura "("



4. A vírgula "," quando a quebra de linha permanece com o elemento que a precede



5. A linha nunca é quebrada diretamente na seta da expressão lambda, a menos seu corpo consiste em uma única expressão sem chaves:

MyLambda<String, Long, Object> lambda =
    (String label, Long value, Object obj) -> {
        ...
    };

Predicate<String> predicate = str ->
    longExpressionInvolving(str);

O principal objetivo das quebras de linha é obter clareza no código, mas não necessariamente o menor número de linhas

4.5.2 Continuação da linha de deslocamento por 4 ou mais espaços

Quando uma linha se quebra, cada substring subsequente dela (cada continuação de linha) é deslocada em pelo menos 4 espaços em relação à anterior.



Quando há várias continuações de linha, o deslocamento pode variar em 4 espaços a pedido do autor. Como regra geral, duas extensões de linha podem ter o mesmo deslocamento se e somente se começarem com elementos sintaticamente paralelos.



A Seção 4.6.3 fornece orientação sobre o uso de quantidades variáveis ​​de espaço em branco para alinhar os pontos de código em relação às linhas anteriores.

4.6 Espaços e recuos

4.6.1 Recuo

Uma linha vazia é sempre colocada:



1. Entre membros sucessivos ou inicializadores de classe: campos, construtores, métodos, classes aninhadas, blocos de inicialização estáticos e dinâmicos

• exceção: uma linha vazia entre dois campos consecutivos (nenhum código entre eles) é opcional. Linhas em branco são usadas para agrupar campos logicamente, se necessário
• exceção: linhas em branco entre constantes de classe enum (consulte a Seção 4.8.1)

2. Consistente com outras seções deste documento (por exemplo, Seção 3 e Seção 3.3). A



linha em branco também pode ser usada para melhorar a legibilidade do código, por exemplo, entre expressões para organizar o código em subseções lógicas. Uma string vazia antes do primeiro membro de uma classe, ou um bloco de inicialização, ou depois do último membro, ou um bloco de inicialização de uma classe é desencorajada, mas não proibida.



Várias linhas em branco consecutivas são permitidas, mas não são necessárias ou incentivadas.

4.6.2 Espaços

Além dos requisitos do próprio idioma ou outras regras deste documento, além de não contar literais e comentários (incluindo Javadoc), os espaços simples da tabela ASCII só podem aparecer nos seguintes locais:



1. Ao separar qualquer palavra reservada, como se, for or catch e um parêntese de abertura "(" que segue



2. Ao separar qualquer palavra reservada, como else ou catch, e uma chave de fechamento "}" que segue



3. Antes de qualquer chave de abertura " {", Exceto para duas situações:

• @SomeAnnotation ({a, b})
• String [] [] x = {{"foo"}}; - espaço entre {{não exigido de acordo com a cláusula 8 abaixo

4. Em qualquer lado de qualquer operador binário ou ternário



Esta regra também se aplica aos seguintes operadores:

• E comercial dentro dos colchetes angulares: <T extends Foo & Bar>
• um delimitador em um bloco catch contendo várias exceções: catch (FooException | BarException e)
• dois pontos ":" em para-cada
• seta na expressão lambda: (String str) -> str.length ()

Mas esta regra não se aplica a operadores:

• dois pontos duplos "::" do método de referência, que é escrito como Object :: toString
• o ponto de separação ".", que é escrito como object.toString ()

5. Depois de ",:;" ou o parêntese de fechamento ")" ao converter para o tipo



6. Em qualquer lado da barra dupla "//" ao criar um comentário na mesma linha de código. Vários espaços são permitidos, mas não obrigatórios aqui



7. Entre a declaração do tipo e o nome da variável:

List<String> list

8. Opcional: dentro dos parênteses do inicializador de array,

new int [] {5, 6} e new int [] {5, 6} são ambos válidos



9. Entre a anotação de tipo e [] ou ...



Esta regra não requer a presença ou ausência de espaços em início ou fim de uma linha; só se aplica a espaços internos.

4.6.3 Alinhamento horizontal nunca é necessário

Terminologia

O alinhamento horizontal é a prática de adicionar um número variável de espaços extras em seu código para fazer certos elementos aparecerem abaixo de outros elementos da linha anterior.



Esta prática é permitida, mas não é exigida por este guia. Também não há necessidade de manter o alinhamento nas partes do código onde ele já foi aplicado.



Um exemplo com e sem alinhamento:

private int x; // 
private Color color; //   

private int   x;      // ,     
private Color color;  //    

O alinhamento melhora a legibilidade do código, mas cria problemas com a manutenção de tal código no futuro. Digamos que você deseja alterar apenas uma linha. Essa alteração pode distorcer a formatação do código aceito anteriormente, o que é aceitável. Mas, muito provavelmente, o programador (talvez você) começará a ajustar o número de espaços nas linhas adjacentes, o que pode desencadear uma série de correções. Mudar uma linha pode desencadear uma “onda explosiva” de trabalho sem sentido (na pior das hipóteses). Ou, na melhor das hipóteses, distorce as informações no histórico da versão, prejudica a legibilidade do código e exacerba os conflitos de mesclagem.

4.7 Parênteses de agrupamento são recomendados

Você só deve omitir os colchetes de agrupamento se o autor do código e o revisor concordarem que não há probabilidade razoável de que o código seja mal interpretado sem parênteses, nem os parênteses tornariam a leitura mais fácil. Não há razão para acreditar que qualquer um que leia o código tenha memorizado toda a tabela de precedência do operador Java.

4.8 Projetos especiais

4.8.1 Classes de enumeração

Uma quebra de linha é opcional após cada vírgula que segue uma constante de enumeração. Linhas em branco extras (geralmente apenas uma) também são permitidas. Aqui está um exemplo desse código:

private enum Answer {
  YES {
    @Override public String toString() {
      return "yes";
    }
  },

  NO,
  MAYBE
}

O código de uma classe de enumeração sem métodos e comentários que descrevem suas constantes pode ser representado como um inicializador de array (consulte a Seção 4.8.3.1):

private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }

Como enums são classes, todas as outras regras que se aplicam a classes devem ser aplicadas a elas.

4.8.2 Declarações de variáveis

4.8.2.1 Uma variável por declaração

Cada variável (campo ou local) é declarada apenas uma de cada vez: declarações como int a, b; não são usados.



Exceção : várias declarações de variáveis ​​são permitidas no cabeçalho de um loop for.

4.8.2.2 Declare variáveis ​​quando você precisar delas

Variáveis ​​locais não precisam ser declaradas no início de um bloco ou construção de bloco. Por outro lado, as variáveis ​​locais devem ser declaradas logo antes de onde serão usadas pela primeira vez para minimizar seu escopo. Normalmente, as variáveis ​​locais são inicializadas no momento da declaração ou imediatamente depois dela.

4.8.3 Matrizes

4.8.3.1 Os inicializadores de array podem ser "bloquear"

Qualquer array pode ser inicializado como se fosse uma construção de bloco. Por exemplo, todo o código a seguir é válido (a lista de exemplos não está completa):

new int[] {
  0, 1, 2, 3
}
                        
new int[] {
  0, 1,
  2, 3
}

new int[]
    {0, 1, 2, 3}

new int[] {
  0,
  1,
  2,
  3
}

4.8.3.2 Nenhuma declaração de array estilo C

Os colchetes são colocados após o tipo, não após a variável: String [] args, não String args [].

4.8.4 A instrução switch

Terminologia

Um ou mais grupos de instruções estão localizados em um bloco de switch. Cada grupo consiste em um ou mais rótulos (ambos caso FOO: e default :) seguidos por uma ou mais declarações (ou, no caso do último grupo, nenhum ou mais).

4.8.4.1 Offset

Como acontece com qualquer outro bloco, o conteúdo do bloco de switch é deslocado por 2 espaços.



Uma quebra de linha é feita após o rótulo do bloco de switch, e o deslocamento é aumentado em 2 espaços, exatamente como quando o bloco foi aberto. Cada rótulo subsequente retorna ao nível de deslocamento anterior, como ao fechar um bloco.

4.8.4.2 Passagem é comentada

Dentro de um bloco, cada grupo de instruções termina antes do planejado com uma mudança (usando break, continue, return ou lançando uma exceção) ou é marcado com um comentário para indicar que a execução do código continuará ou poderá continuar no próximo grupo. Qualquer comentário transmitindo a ideia de uma passagem direta (geralmente // falha) é suficiente. Este comentário não é necessário no último grupo do bloco de switch. Exemplo:

switch (input) {
  case 1:
  case 2:
    prepareOneOrTwo();
    // fall through
  case 3:
    handleOneTwoOrThree();
    break;
  default:
    handleLargeNumber(input);
}

Observe que o comentário não é colocado após o caso 1, mas apenas no final do grupo de declarações.

4.8.4.3 Sempre usar padrão

A instrução switch deve conter o rótulo padrão, mesmo se não houver nenhum código nele.



Exceção : Um bloco de switch para um tipo de enum pode não usar o padrão se contiver casos explícitos cobrindo todos os valores possíveis desse tipo. Isso permite que o IDE ou outras ferramentas de análise estática emitam um aviso de que alguns casos não são cobertos.

4.8.5 Anotações

As anotações aplicadas a uma classe, método ou construtor seguem imediatamente após o bloco doc. Cada anotação é indicada em sua própria linha (ou seja, uma anotação por linha). Essas quebras de linha não são quebras de linha (consulte a Seção 4.5), portanto, o nível de recuo não é aumentado. Exemplo:

@Override
@Nullable
public String getNameIfPresent() { ... }

Exceção : uma única anotação sem parâmetros pode ser exibida junto com a primeira linha de assinatura, por exemplo:

@Override public int hashCode() { ... }

As anotações aplicadas a um campo também aparecem imediatamente após o bloco de documentos, mas, neste caso, várias anotações (possivelmente parametrizadas) podem ser listadas na mesma linha, por exemplo:

@Partial @Mock DataLoader loader;

Não existem regras especiais para formatar anotações para parâmetros, variáveis ​​locais ou tipos.

4.8.6 Comentários

Esta seção é dedicada a comentários de implementação. Javadoc é discutido separadamente na Seção 7.



Qualquer quebra de linha pode ser precedida por um número arbitrário de espaços, seguido por um comentário de implementação. Este comentário torna a linha não vazia.

4.8.6.1 Bloquear estilo de comentário

O nível de indentação de um comentário de bloco é o mesmo do código ao redor. Os comentários em bloco podem ser / *… * / ou //… Para comentários de várias linhas como / *… * /, as linhas subsequentes devem começar com *, alinhadas com * na linha anterior.

/*
 * This is          // And so           /* Or you can
 * okay.            // is this.          * even do this. */
 */

Os comentários não são colocados em retângulos representados por asteriscos ou outros símbolos.

Ao escrever comentários de várias linhas, use o estilo / * ... * / se desejar que o formatador de código automático quebre a linha conforme necessário (no estilo de parágrafos). A maioria dos formatadores não pode fazer isso com blocos de comentário de linha única // ...

4.8.7 Modificadores

Modificadores de classe e campo, se presentes, são exibidos na ordem recomendada pela especificação da linguagem Java:

public protected private abstract default static final transient volatile synchronized native strictfp

4.8.8 Literais numéricos

O tipo longo usa L maiúsculo, não minúsculo (para não ser confundido com o número 1). Por exemplo, 300_000_000L em vez de 300_000_000l.

5. Nomenclatura

5.1 Regras gerais para todos os identificadores

Os identificadores usam apenas letras e números ASCII e, em alguns casos observados abaixo, sublinhados.



Portanto, todo nome de identificador válido é correspondido pela expressão regular \ w + (um caractere alfanumérico que ocorre uma ou mais vezes).



Nomes que usam sufixos ou prefixos especiais, como name_, mName, s_name ou kName, não estão de acordo com o estilo deste tutorial.

5.2 Regras para diferentes tipos de identificadores

5.2.1 Nomes de pacotes

Os nomes dos pacotes devem ser escritos em minúsculas, sem camelCase ou sublinhados.



Correto: com.example.deepspace

Incorreto: com.example.deepSpace ou com.example.deep_space

5.2.2 Nomes de classes

Os nomes das classes são escritos no estilo UpperCamelCase (primeira letra maiúscula).



Os nomes das classes são geralmente substantivos ou sintagmas nominais. Por exemplo, Character ou ImmutableList.



Os nomes de interface também podem ser substantivos ou sintagmas nominais (por exemplo, Lista), mas às vezes também podem ser adjetivos ou combinações de adjetivos (por exemplo, Legível).



Não existem regras específicas ou mesmo convenções bem estabelecidas para nomear tipos de anotação.



As classes de teste têm um nome que começa com o nome da classe que estão testando e termina com a palavra Teste. Por exemplo, HashTest ou HashIntegrationTest.

5.2.3 Nomes de métodos

Os nomes dos métodos são escritos no estilo lowerCamelCase.



Os nomes dos métodos geralmente são verbos ou frases verbais. Por exemplo, sendMessage ou stop.



Os sublinhados podem ser usados ​​em nomes de métodos de teste JUnit para separar componentes lógicos no nome. Além disso, cada componente é escrito no estilo lowerCamelCase. O padrão típico é:

<methodUnderTest>_<state>, , pop_emptyStack

Não existe uma única maneira correta de nomear métodos de teste.

5.2.4 Nomes de constantes

As constantes são nomeadas no estilo CONSTANT_CASE: todas as letras são maiúsculas, cada palavra separada da seguinte por um sublinhado. Mas o que exatamente é uma constante?



Constantes são campos finais estáticos cujo conteúdo é imutável e métodos que não têm efeitos colaterais visíveis. Isso se aplica a primitivos, Strings, tipos imutáveis ​​e coleções imutáveis ​​de tipos imutáveis. Se qualquer estado observável de um objeto pode mudar, ele não é uma constante. A simples intenção de nunca modificar um objeto não é suficiente.



Exemplos:

// 
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final ImmutableMap<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32);
static final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }

//  
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final Set<String> mutableCollection = new HashSet<String>();
static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);
static final ImmutableMap<String, SomeMutableType> mutableValues =
    ImmutableMap.of("Ed", mutableInstance, "Ann", mutableInstance2);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};

Nomes constantes são geralmente substantivos ou sintagmas nominais.

5.2.5 Nomes de campos não constantes

Os nomes dos campos que não são constantes (estáticos ou não) são escritos no estilo lowerCamelCase.



Os nomes de tais campos são geralmente substantivos ou sintagmas nominais. Por exemplo, computedValues ​​ou index.

5.2.6 Nomes de parâmetros

Os nomes dos parâmetros são escritos no estilo lowerCamelCase.



Nomes de parâmetros de um caractere devem ser evitados em métodos públicos.

5.2.7 Nomes de variáveis ​​locais

Os nomes das variáveis ​​locais são escritos no estilo lowerCamelCase.



Mesmo sendo finais e imutáveis, as variáveis ​​locais não são consideradas constantes e não devem ser escritas no mesmo estilo das constantes.

5.2.8 Nomes de variáveis ​​de tipo

Cada variável de tipo é nomeada de acordo com um de dois estilos:

• Uma única letra maiúscula, que pode ser seguida por um número regular (por exemplo, E, T, X, T2)
• Um nome na forma de um nome de classe (consulte a Seção 5.2.2) seguido por uma letra T maiúscula (exemplos: RequestT, FooBarT).

5.3 Estilo Camel (camelCase)

Às vezes, há mais de uma maneira de converter uma frase em inglês para o estilo camelo, como no caso de abreviações ou expressões atípicas como “IPv6” ou “iOS”.



Para aumentar a previsibilidade, este guia apresenta o seguinte esquema (exemplar).



Começando com a forma original do nome:



1. Converta a frase para ASCII regular e remova todos os apóstrofos. Por exemplo, o "algoritmo de Müller" pode ser convertido em "algoritmo de Muellers"



2. Divida o resultado em palavras, descartando os espaços e a pontuação restante (geralmente hifens):

• recomendação: se alguma palavra já tiver uma forma comum no estilo “camelo” usual, divida-a nas partes que a compõem (por exemplo, “AdWords” é convertido em “palavras de anúncio”). Observe que uma palavra como “iOS” não é realmente um estilo camelo; não cumpre nenhuma convenção, portanto esta recomendação não se aplica.

3. Agora converta tudo para minúsculas (incluindo abreviações) e, em seguida, converta para maiúsculas o primeiro caractere:

• ... em cada palavra para alcançar o estilo UpperCamelCase, ou
• ... em todas as palavras, exceto a primeira para alcançar o estilo lowerCamelCase

4. Finalmente, concatene todas as palavras em um único identificador.



Observe que a capitalização das palavras originais é quase completamente ignorada.



Exemplos:



* Permitido, mas não recomendado.



Observação : algumas palavras em inglês usam um hífen de forma ambígua: por exemplo, "não vazio" e "não vazio" estão corretos, portanto, os nomes dos métodos checkNonempty e checkNonEmpty também estão corretos.

6. Prática de programação

6.1 Sempre use a anotação @Override

O método é marcado com a anotação @Override sempre que é realmente substituído. Isso se aplica tanto ao método da classe descendente que substitui o método da classe pai quanto ao método da interface que substitui o método da superinterface.



Exceção : a anotação pode ser omitida se o método pai estiver marcado com a anotação @Deprecated.

6.2 Não ignore as exceções detectadas

É muito raro que haja situações em que você não precise realizar nenhuma ação em resposta a uma exceção detectada (uma solução típica é registrá-la ou, se for considerada "impossível", lançar a exceção como um AssertionError).



Abaixo está um exemplo com um comentário explicativo quando é realmente apropriado não realizar nenhuma ação no bloco catch:

try {
  int i = Integer.parseInt(response);
  return handleNumericResponse(i);
} catch (NumberFormatException ok) {
  // it's not numeric; that's fine, just continue
}
return handleTextResponse(response);

Exceção : Em testes, uma exceção detectada pode ser ignorada e descomentada se o nome do teste for esperado ou se o nome começar com o esperado. O seguinte é um idioma muito comum, mostrando que o código em teste lança uma exceção do tipo esperado, portanto, nenhum comentário é necessário aqui:

try {
  emptyStack.pop();
  fail();
} catch (NoSuchElementException expected) {
}

6.3 Para membros estáticos, use o nome da classe

É necessário acessar um membro de uma classe estática por meio do nome da classe, e não por referência a um objeto de classe ou por uma expressão que retorne esse objeto:

Foo aFoo = ...;
Foo.aStaticMethod(); // 
aFoo.aStaticMethod(); // 
somethingThatYieldsAFoo().aStaticMethod(); //  

6.4 Não use finalizadores

É extremamente raro que você precise substituir o método Object.finalize.



Dica :



não faça isso. Se você realmente precisar, primeiro leia e realmente entenda completamente o Effective Java Item 7, “Evite finalizadores”, e depois não.

7. Javadoc

7.1 Formatação

7.1.1 Formulário principal

A formatação simples de blocos Javadoc segue este exemplo:

/**
 * Multiple lines of Javadoc text are written here,
 * wrapped normally...
 */
public int method(String p1) { ... }

... ou em uma linha:

/** An especially short bit of Javadoc. */

O formulário simples é sempre aplicável. A forma de linha única pode ser aplicada quando todo o bloco Javadoc (incluindo marcadores de comentários) pode caber em uma linha. Observe que isso só é aplicável quando o bloco não contém tags como @return.

7.1.2 Parágrafos

Uma linha em branco, ou seja, uma linha contendo apenas um asterisco inicial alinhado (*), aparece entre os parágrafos e antes do grupo de tag do bloco, se houver. Cada parágrafo, exceto o primeiro, contém um <p> imediatamente antes da primeira palavra, sem espaço depois.

7.1.3 Tags de bloco

Todas as tags de bloco estão nesta ordem: @param, @return, @throws, @deprecated e esses quatro tipos nunca estão presentes com descrições vazias. Se uma etiqueta de bloco não couber em uma linha, as linhas de continuação são recuadas quatro (ou mais) espaços de @.

7.2 Fragmento final

Cada bloco Javadoc começa com um pequeno trecho de resumo. Este snippet é muito importante: é o único texto que aparece em um contexto específico, como índices de classe e método.



Este trecho é um substantivo ou frase verbal, não uma frase completa. Não começa com A {@code Foo} é um ... ou Este método retorna ..., nem forma uma frase afirmativa completa como Salvar o registro. No entanto, esta passagem é maiúscula e pontuada como se fosse uma frase completa.



Dica : é um erro comum escrever um Javadoc simples como / ** @return the customer ID * /. Isso está incorreto e deve ser corrigido para / ** Retorna o ID do cliente. * /.

7.3 Quando Javadoc é aplicado

Javadoc está presente em pelo menos todas as classes públicas e todos os membros públicos e protegidos dessa classe, exceto em alguns casos, descritos abaixo.

Javadoc adicional pode estar presente, conforme explicado na Seção 7.3.4, Javadoc opcional.

7.3.1 Exceção: métodos que se descrevem

Javadoc é opcional para métodos simples e óbvios como getFoo, nos casos em que você realmente não pode dizer mais do que "Retorna foo".



Importante : É impróprio referir-se a esta exceção para justificar a omissão de informações relevantes que o leitor comum possa precisar.



Por exemplo, para um método chamado getCanonicalName, não omita a documentação (com a justificativa de que o nome do método diz apenas / ** Retorna o nome canônico. * /) Se a pessoa comum que lê o código nem mesmo suspeita do que o termo "nome canônico" significa !

7.3.2 Exceção: Substituir

Javadoc nem sempre acompanha um método que substitui um método de uma superclasse (ou superinterface).

7.3.4 Javadoc Opcional

Outras classes e membros são acompanhados por Javadoc conforme necessário ou desejado.



Sempre que um comentário de implementação for usado para definir o propósito geral ou comportamento de uma classe ou membro, esse comentário é escrito como Javadoc (usando / **).



O Javadoc opcional não precisa seguir as regras de formatação das Seções 7.1.2, 7.1.3 e 7.2, embora isso seja obviamente recomendado.



Esta tradução também está disponível em nosso blog.