Guía de Google para formatear código Java

1. Introducción

Este documento describe los estándares para codificar en el lenguaje de programación Java en Google. Se considera que el código fuente de Java cumple con estos estándares si, y solo si, cumple con todas las reglas descritas en este documento.



Los temas que se tratan en este tutorial no son solo sobre el lado estético del formato de código, sino también sobre otros tipos de convenciones o estándares de codificación. Sin embargo, este documento se concentra principalmente en definir las reglas estrictas que seguimos en todas partes y no proporciona recomendaciones que puedan implementarse incorrectamente (tanto por humanos como por máquinas herramienta).

1.1 Terminología

A lo largo de esta guía, se definen los siguientes términos:

1. El término clase se usa para referirse a una clase, enumeración, interfaz o tipo de anotación "regular" (@interface)
2. El término miembro de clase se utiliza para hacer referencia a una clase, campo, método o constructor anidado, es decir, para todos los miembros de clase de alto nivel, excepto los bloques de inicialización y los comentarios.
3. El término comentario siempre se refiere a comentarios de implementación. No utilizamos la frase "comentarios de documentación", sino el término "Javadoc".

El resto de la terminología se proporcionará según sea necesario a lo largo de este manual.

1.2 Nota de guía

Los ejemplos de código de este documento no demuestran el único enfoque estilístico correcto para su formato, aunque se utilizan en nuestro tutorial.

2. Archivo fuente. Los basicos

2.1 Nombre de archivo

El nombre del archivo de origen consiste en el nombre de una clase particular de nivel superior que reside en él. El nombre distingue entre mayúsculas y minúsculas y termina con una extensión .java

2.2 Codificación de archivo: UTF-8

Los archivos con código están codificados en UTF-8.

2.3 Caracteres especiales

2.3.1 Caracteres espaciales

Aparte de la secuencia de caracteres de fin de línea, el carácter de espacio ASCII horizontal (0x20) es el único carácter delimitador que se encuentra en el archivo fuente. Esto significa que:

1. Todos los demás caracteres de espacio en blanco en los literales de caracteres y cadenas se escapan
2. Los caracteres de tabulación no se utilizan para la sangría

2.3.2 Secuencias de escape especiales

Para cada carácter para el que hay una secuencia de escape especial (\ b, \ t, \ n, \ f, \ r, \ ", \ 'y \\), es preferible usarlo en lugar de su valor octal correspondiente (por ejemplo, \ 012 ) o código Unicode (por ejemplo, \ u000a).

2.3.3 Caracteres no ASCII

Para caracteres no ASCII, use el carácter Unicode (por ejemplo, ∞) o una secuencia de escape equivalente (por ejemplo, \ u221e). La elección se da a favor de aquellos símbolos que hacen que el código sea más comprensible y legible.

Cuando utilice caracteres de escape Unicode y en los casos en que se utilicen caracteres Unicode válidos, recomendamos encarecidamente que dicho código vaya acompañado de comentarios explicativos.

Nunca haga que su código sea menos legible por temor a que algunos programas no puedan procesar correctamente los caracteres no ASCII. Si esto sucede, dichos programas no funcionan correctamente y deben repararse.

3. Estructura del archivo de origen

El archivo de origen consta de los siguientes elementos (en el orden que se muestra):

1. Licencia o información de derechos de autor, si corresponde
2. Declaración de paquete
3. Declaración de importaciones
4. Declaración de clase

Exactamente una línea en blanco separa cada sección presente.

3.1 Licencia o información de derechos de autor, si corresponde

La información de licencia o derechos de autor debe incluirse en el archivo al que se refiere.

3.2 Declaración del paquete

El paquete se declara sin salto de línea. La limitación de ancho de línea (Sección 4.4) no se aplica a una declaración de paquete.

3.3 Declaraciones de importación

3.3.1 Comodín en declaraciones de importación

El carácter * (comodín) no se utiliza al declarar importaciones, estáticas o no.

3.3.2 Salto de línea

Las importaciones se declaran sin saltos de línea. No están sujetos al límite de ancho de línea.

3.3.3 Orden y espaciado

Las importaciones se ordenan de la siguiente manera:

1. Todas las importaciones estáticas se colocan y agrupan en un bloque
2. Todas las importaciones no estáticas se colocan en otro bloque

Si se declaran importaciones estáticas y no estáticas, estos bloques deben estar separados por una línea vacía. No debe haber otras líneas en blanco entre ellos.



Dentro de cada bloque, las clases importadas se enumeran en el orden de clasificación de los caracteres ASCII.

3.3.4 Importación estática de clases anidadas

Las importaciones estáticas no se utilizan para clases anidadas estáticas. Estas clases se importan con una declaración de importación regular.

3.4 Declaración de clase

3.4.1 Se declara exactamente una clase de nivel superior

Cada clase de nivel superior se encuentra en su propio archivo fuente.

3.4.2 Ordenar los contenidos de una clase

El orden en el que coloque los miembros y los bloques de inicialización de una clase puede tener un gran impacto en la facilidad de comprensión del código. De cualquier manera, no existe una receta simple y correcta para esto; diferentes clases pueden organizar su contenido de manera diferente.



Lo importante es que cada clase tenga un orden lógico de contenido para que el programador que lee el código pueda explicarlo.

3.4.2.1 El código sobrecargado no debe dividirse

Cuando una clase tiene varios constructores o métodos con el mismo nombre, deben colocarse secuencialmente sin insertar otro código entre ellos.

4. Formateo

Terminología

El cuerpo de una clase, método o constructor es una construcción de bloque .



Tenga en cuenta que de acuerdo con la Sección 4.8.3.1, cualquier inicializador de matriz también puede considerarse una construcción de bloque.

4.1 Tirantes rizados

4.1.1 Los tirantes rizados se utilizan dondequiera que se puedan utilizar

Las llaves se utilizan en if, else, for, while y do-while, incluso si el cuerpo de la expresión está vacío o contiene solo una línea de código.

4.1.2 Bloques no en blanco: estilo K&R

Las llaves se colocan de acuerdo con el estilo de Kernighan y Ritchie ("corchetes egipcios") para bloques no vacíos y estructuras de bloques (para mayor claridad, decidimos agregar un pequeño código que demuestra estas reglas - nota del traductor):

• No se realiza ningún salto de línea antes del paréntesis de apertura:

// 
if (true) { 

// 
if (true)
{

• Se realiza un salto de línea después del paréntesis de apertura:

// 
while (true) {
  // code

// 
while (true) { // code

• Se realiza un salto de línea antes del paréntesis de cierre:

// 
for () {
  // code
}

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

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

• Un salto de línea ocurre después de un paréntesis de cierre solo si ese paréntesis termina una expresión o cuerpo de un método, constructor o clase no anónima. El salto de línea no se realiza después de un paréntesis si va seguido de un else, una captura o un punto y coma

Ejemplos de reglas ejecutadas correctamente:

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();
    }
  }
};

En la Sección 4.8.1 se dan algunas excepciones para las enumeraciones.

4.1.3 Los bloques vacíos se pueden comprimir

Un bloque vacío o una construcción de bloque vacío puede seguir el estilo K & R (como se describe en la Sección 4.1.2). También es posible que dicho bloque se cierre inmediatamente después de abrirse, sin caracteres ni saltos de línea dentro de {}. Esta regla no se aplica cuando el bloque es parte de una expresión de bloques múltiples que contiene un if-else o try-catch-tomorrow.



Ejemplos:

// 
void doNothing() {}

//  
void doNothingElse() {
}

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

4.2 Dos espacios para sangría

Cada vez que se abre un nuevo bloque o construcción de bloque, el desplazamiento a la derecha aumenta en dos espacios. Cuando termina un bloque, el comienzo de la siguiente línea de código se desplaza al nivel de compensación anterior. El nivel de compensación se aplica tanto al bloque como a los comentarios en ese bloque (vea el ejemplo en la Sección 4.1.2).

4.3 Una expresión por línea

Cada expresión termina con un salto de línea.

4.4 Limitar el ancho de línea a 100 caracteres

El código Java está limitado a 100 caracteres de ancho de línea. Un "carácter" se refiere a cualquiera de los elementos Unicode. Excepto como se describe a continuación, cada línea que exceda el límite de ancho se debe envolver como se explica en la Sección 4.5.



Excepciones:

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

4.5

Cuando el código que de otro modo podría estar en la misma línea se divide en varias líneas, este fenómeno se denomina salto de línea.



No existe una fórmula inequívoca generalmente aceptada que determine exactamente cómo se deben realizar los saltos de línea en cada situación. Muy a menudo, hay varias formas de romper una línea con el mismo código.



Por lo general, el ajuste se realiza para evitar el desbordamiento del ancho de línea. Pero incluso si el código se mantiene dentro del ancho permitido, entonces, a decisión del autor, se puede ajustar a una nueva línea.

La asignación de un método auxiliar o variable local puede resolver el problema de desbordamiento del ancho de línea sin envolver el código

4.5.1 Dónde transferir

La primera pauta para los saltos de línea dice: es preferible hacer el salto de línea a un nivel sintáctico más alto. Además:



1. Cuando se rompe una línea en una declaración de no asignación, la ruptura se realiza antes del carácter.



Esta regla también se aplica a los siguientes caracteres "similares a operadores":

• punto de división "."
• dos puntos dobles del método de referencia "::"
• ampersand entre paréntesis genérico <T extiende Foo & Bar>
• delimitador en el bloque de captura (FooException | BarException e)

2. Cuando una cadena está envuelta en una instrucción de asignación, normalmente se realiza después del carácter, pero



se acepta otra solución, que también se aplica a los dos puntos del bucle for-each.



3. El nombre del método o constructor cuando los saltos de línea permanece adjunto al paréntesis de apertura "("



4. La coma "," cuando el salto de línea permanece con el elemento que lo precede



5. La línea nunca se ajusta directamente a la flecha de la expresión lambda, a menos que su cuerpo consta de una sola expresión sin llaves:

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

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

El propósito principal de los saltos de línea es lograr claridad en el código, pero no necesariamente el menor número de líneas.

4.5.2 Continuación de la línea compensada en 4 o más espacios

Cuando se rompe una línea, cada subcadena posterior (cada continuación de línea) se desplaza al menos 4 espacios con respecto a la anterior.



Cuando hay varias continuaciones de línea, el desplazamiento puede variar en 4 espacios a petición del autor. Como regla general, dos extensiones de línea pueden tener el mismo desplazamiento si y solo si comienzan con elementos sintácticamente paralelos.



La sección 4.6.3 proporciona orientación sobre el uso de cantidades variables de espacio en blanco para alinear puntos de código en relación con líneas anteriores.

4.6 Espacios y sangrías

4.6.1 Sangría

Siempre se coloca una línea vacía:



1. Entre miembros sucesivos o inicializadores de clase: campos, constructores, métodos, clases anidadas, bloques de inicialización estáticos y dinámicos.

• excepción: una línea vacía entre dos campos consecutivos (sin código entre ellos) es opcional. Las líneas en blanco se utilizan para agrupar campos de forma lógica si es necesario
• excepción: líneas en blanco entre las constantes de clase de enumeración (consulte la Sección 4.8.1)

2. De acuerdo con otras secciones de este documento (por ejemplo, Sección 3 y Sección 3.3) La



línea en blanco también se puede utilizar en todas partes para mejorar la legibilidad del código, por ejemplo, entre expresiones para organizar el código en subsecciones lógicas. Una cadena vacía antes del primer miembro de una clase, o un bloque de inicialización, o después del último miembro, o un bloque de inicialización de una clase no se recomienda, pero no se prohíbe.



Se permiten varias líneas en blanco consecutivas, pero no son necesarias ni recomendadas.

4.6.2 Espacios

Aparte de los requisitos del lenguaje en sí u otras reglas de este documento, además de no contar literales y comentarios (incluido Javadoc), los espacios simples de la tabla ASCII solo pueden estar presentes en los siguientes lugares:



1. Al separar cualquier palabra reservada como si, for or catch y un paréntesis de apertura "(" que sigue a



2. Al separar cualquier palabra reservada, como else o catch, y una llave de cierre "}" que sigue a



3. Antes de cualquier llave de apertura " {", Excepto en dos situaciones:

• @Algunas anotaciones ({a, b})
• Cadena [] [] x = {{"foo"}}; - espacio entre {{no se requiere según la cláusula 8 a continuación

4. A ambos lados de cualquier operador binario o ternario



Esta regla también se aplica a los siguientes operadores:

• y corchetes angulares interiores: <T extiende Foo & Bar>
• un delimitador en un bloque catch que contiene varias excepciones: catch (FooException | BarException e)
• dos puntos ":" en cada uno
• flecha en expresión lambda: (String str) -> str.length ()

Pero esta regla no se aplica a los operadores:

• dos puntos dobles "::" del método de referencia, que está escrito como Object :: toString
• el punto de separación ".", que se escribe como object.toString ()

5. Después de ",:;" o el paréntesis de cierre ")" cuando se convierte al tipo



6. A cada lado de la barra doble "//" al crear un comentario en la misma línea de código. Se permiten varios espacios, pero no se requieren aquí



7. Entre la declaración de tipo y el nombre de la variable:

List<String> list

8. Opcional: dentro de los paréntesis del inicializador de matriz,

new int [] {5, 6} y new int [] {5, 6} son válidos



9. Entre la anotación de tipo y [] o ...



Esta regla no requiere la presencia o ausencia de espacios en comienzo o final de una línea; solo se aplica a los espacios internos.

4.6.3 Nunca se requiere alineación horizontal

Terminología

La alineación horizontal es la práctica de agregar un número variable de espacios adicionales en su código para hacer que ciertos elementos aparezcan debajo de otros elementos de la línea anterior.



Esta práctica está permitida pero no es requerida por esta guía. Tampoco es necesario mantener la alineación en aquellas partes del código donde ya se ha aplicado.



Ejemplo con y sin alineación:

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

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

La alineación mejora la legibilidad del código, pero crea problemas para mantener dicho código en el futuro. Digamos que solo desea cambiar una línea. Este cambio puede dañar el formato del código previamente aceptado, lo cual es aceptable. Pero, lo más probable es que el programador (tal vez usted) comience a ajustar el número de espacios en las líneas adyacentes, lo que puede desencadenar toda una serie de correcciones. Cambiar una línea puede desencadenar una "ola explosiva" de trabajo sin sentido (en el peor de los casos). O, en el mejor de los casos, distorsionará la información del historial de versiones, afectará la legibilidad del código y agravará los conflictos de fusión.

4.7 Se recomiendan los soportes de agrupación

Solo debe omitir los corchetes de agrupación si el autor del código y el revisor están de acuerdo en que no hay una probabilidad razonable de que el código se malinterprete sin paréntesis, ni los paréntesis facilitarían la lectura. No hay razón para creer que todos los que leen el código han memorizado toda la tabla de precedencia de operadores de Java.

4.8 Diseños especiales

4.8.1 Clases de enumeración

Un salto de línea es opcional después de cada coma que sigue a una constante de enumeración. También se permiten líneas en blanco adicionales (generalmente solo una). Aquí hay un ejemplo de dicho código:

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

  NO,
  MAYBE
}

El código de una clase de enumeración sin métodos y comentarios que describan sus constantes se puede representar como un inicializador de matriz (consulte la Sección 4.8.3.1):

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

Dado que las enumeraciones son clases, todas las demás reglas que se aplican a las clases deberían aplicarse a ellas.

4.8.2 Declaraciones de variables

4.8.2.1 Una variable por declaración

Cada variable (de campo o local) se declara solo una a la vez: declaraciones como int a, b; no se utilizan.



Excepción : se permiten múltiples declaraciones de variables en el encabezado de un bucle for.

4.8.2.2 Declare variables cuando las necesite

Las variables locales no tienen que declararse al comienzo de una construcción de bloque o bloque. Por el contrario, las variables locales deben declararse justo antes de que se utilicen por primera vez para minimizar su alcance. Por lo general, las variables locales se inicializan en el momento de la declaración o inmediatamente después.

4.8.3 Matrices

4.8.3.1 Los inicializadores de matriz pueden ser "bloque"

Cualquier matriz se puede inicializar como si fuera una construcción de bloque. Por ejemplo, todo el código siguiente es válido (la lista de ejemplos no 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 Sin declaraciones de matrices de estilo C

Los corchetes se colocan después del tipo, no después de la variable: String [] args, no String args [].

4.8.4 La declaración de cambio

Terminología

Uno o más grupos de declaraciones se encuentran dentro de un bloque de interruptores. Cada grupo consta de una o más etiquetas (ambas en caso FOO: y por defecto :) seguidas de una o más declaraciones (o, en el caso del último grupo, ninguna o más).

4.8.4.1 Desplazamiento

Como con cualquier otro bloque, el contenido del bloque de interruptores está compensado por 2 espacios.



Se realiza un salto de línea después de la etiqueta del bloque de interruptores y el desplazamiento se incrementa en 2 espacios, al igual que cuando se abrió el bloque. Cada etiqueta siguiente vuelve al nivel de compensación anterior, como al cerrar un bloque.

4.8.4.2 Se comenta la transferencia

Dentro de un bloque, cada grupo de declaraciones termina antes de lo programado con un interruptor (usando romper, continuar, regresar o lanzar una excepción), o está marcado con un comentario para indicar que la ejecución del código continuará o puede continuar en el siguiente grupo. Cualquier comentario que transmita la idea de un pasaje a través (generalmente // pasar) es suficiente. Este comentario no es necesario en el último grupo del bloque de interruptores. Ejemplo:

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

Tenga en cuenta que el comentario no se coloca después del caso 1, sino solo al final del grupo de declaraciones.

4.8.4.3 Usar siempre predeterminado

La declaración de cambio debe contener la etiqueta predeterminada, incluso si no contiene ningún código.



Excepción : un bloque de conmutación para un tipo de enumeración puede no usar default si contiene casos explícitos que cubran todos los valores posibles de ese tipo. Esto permite que el IDE u otras herramientas de análisis estático emitan una advertencia de que algunos casos no están cubiertos.

4.8.5 Anotaciones

Las anotaciones aplicadas a una clase, método o constructor siguen inmediatamente después del bloque doc. Cada anotación se indica en su propia línea (es decir, una anotación por línea). Estos saltos de línea no son saltos de línea (consulte la Sección 4.5), por lo que el nivel de sangría no aumenta. Ejemplo:

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

Excepción : se puede mostrar una única anotación sin parámetros junto con la primera línea de firma, por ejemplo:

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

Las anotaciones aplicadas a un campo también aparecen inmediatamente después del bloque doc, pero en este caso, se pueden enumerar varias anotaciones (posiblemente parametrizadas) en la misma línea, por ejemplo:

@Partial @Mock DataLoader loader;

No hay reglas especiales para dar formato a las anotaciones de parámetros, variables locales o tipos.

4.8.6 Comentarios

Esta sección está dedicada a los comentarios sobre la implementación. Javadoc se analiza por separado en la Sección 7.



Cualquier salto de línea puede ir precedido de un número arbitrario de espacios, seguido de un comentario de implementación. Este comentario hace que la línea no esté vacía.

4.8.6.1 Estilo de comentario de bloque

El nivel de sangría de un comentario de bloque es el mismo que el del código circundante. Los comentarios de bloque pueden ser / *… * / o //… Para comentarios de varias líneas como / *… * /, las líneas siguientes deben comenzar con un *, alineadas con un * de la línea anterior.

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

Los comentarios no se encierran en rectángulos representados por asteriscos u otros símbolos.

Al escribir comentarios de varias líneas, utilice el estilo / * ... * / si desea que el formateador de código automático divida la línea según sea necesario (al estilo de los párrafos). La mayoría de los formateadores no pueden hacer esto con bloques de comentarios de una sola línea // ...

4.8.7 Modificadores

Los modificadores de clase y campo, si están presentes, se muestran en el orden recomendado por la especificación del lenguaje Java:

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

4.8.8 Literales numéricos

El tipo largo usa una L mayúscula, no minúscula (para no confundirse con el número 1). Por ejemplo, 300_000_000L en lugar de 300_000_000l.

5. Nombrar

5.1 Reglas generales para todos los identificadores

Los identificadores usan solo letras y números ASCII y, en algunos casos que se indican a continuación, guiones bajos.



Por lo tanto, cada nombre de identificador válido se corresponde con la expresión regular \ w + (un carácter alfanumérico que aparece una o más veces).



Los nombres que utilizan sufijos o prefijos especiales, como name_, mName, s_name o kName, no se ajustan al estilo de este tutorial.

5.2 Reglas para diferentes tipos de identificadores

5.2.1 Nombres de paquetes

Los nombres de los paquetes deben escribirse en minúsculas, sin camelCase ni guiones bajos.



Correcto: com.example.deepspace

Incorrecto: com.example.deepSpace o com.example.deep_space

5.2.2 Nombres de clases

Los nombres de las clases están escritos en el estilo UpperCamelCase (primera letra en mayúscula).



Los nombres de las clases suelen ser sustantivos o frases nominales. Por ejemplo, Character o ImmutableList.



Los nombres de interfaz también pueden ser sustantivos o frases nominales (por ejemplo, List), pero a veces también pueden ser adjetivos o combinaciones de adjetivos (por ejemplo, Readable).



No existen reglas específicas ni convenciones bien establecidas para nombrar tipos de anotaciones.



Las clases de prueba tienen un nombre que comienza con el nombre de la clase que están probando y termina con Prueba. Por ejemplo, HashTest o HashIntegrationTest.

5.2.3 Nombres de métodos

Los nombres de los métodos están escritos en el estilo lowerCamelCase.



Los nombres de los métodos suelen ser verbos o frases verbales. Por ejemplo, sendMessage o stop.



Se pueden usar guiones bajos en los nombres de los métodos de prueba JUnit para separar componentes lógicos en el nombre. Además, cada componente está escrito en el estilo lowerCamelCase. El patrón típico es:

<methodUnderTest>_<state>, , pop_emptyStack

No existe una única forma correcta de nombrar los métodos de prueba.

5.2.4 Nombres de constantes

Las constantes se nombran en el estilo CONSTANT_CASE: todas las letras están en mayúsculas, cada palabra separada de la siguiente por un guión bajo. Pero, ¿qué es exactamente una constante?



Las constantes son campos finales estáticos cuyo contenido es inmutable y métodos que no tienen efectos secundarios visibles. Esto se aplica a primitivas, cadenas, tipos inmutables y colecciones inmutables de tipos inmutables. Si cualquier estado observable de un objeto puede cambiar, no es una constante. La simple intención de no modificar nunca un objeto no es suficiente.



Ejemplos:

// 
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"};

Los nombres constantes suelen ser sustantivos o frases nominales.

5.2.5 Nombres de campos no constantes

Los nombres de los campos que no son constantes (estáticos o no) se escriben en el estilo lowerCamelCase.



Los nombres de dichos campos suelen ser sustantivos o frases nominales. Por ejemplo, computedValues ​​o index.

5.2.6 Nombres de parámetros

Los nombres de los parámetros están escritos en el estilo lowerCamelCase.



En los métodos públicos, se deben evitar los nombres de parámetros de un carácter.

5.2.7 Nombres de variables locales

Los nombres de las variables locales se escriben en el estilo lowerCamelCase.



Aunque son finales e inmutables, las variables locales no se consideran constantes y no deben escribirse con el mismo estilo que las constantes.

5.2.8 Nombres de variables de tipo

Cada variable de tipo se nombra según uno de dos estilos:

• Letra mayúscula única, que puede ir seguida de un número regular (por ejemplo, E, T, X, T2)
• Un nombre en forma de nombre de clase (consulte la Sección 5.2.2) seguido de una letra T mayúscula (ejemplos: RequestT, FooBarT).

5.3 Estilo camello (camelCase)

A veces hay más de una forma de convertir una frase en inglés al estilo camel, como en el caso de abreviaturas o expresiones atípicas como “IPv6” o “iOS”.



Para aumentar la previsibilidad, esta guía establece el siguiente esquema (ejemplar).



Comenzando con la forma original del nombre:



1. Convierta la frase a ASCII normal y elimine todos los apóstrofos. Por ejemplo, el "algoritmo de Müller" se puede convertir en el "algoritmo de Muellers"



2. Divida el resultado en palabras, descartando los espacios y la puntuación restante (generalmente guiones):

• recomendación: si alguna palabra ya tiene una forma común en el estilo habitual de "camello", divídala en sus partes componentes (por ejemplo, "AdWords" se convierte en "palabras publicitarias"). Tenga en cuenta que una palabra como "iOS" no es realmente estilo camello; no cumple con ningún convenio, por lo que esta recomendación no se aplica.

3. Ahora convierta todo a minúsculas (incluidas las abreviaturas), luego convierta a mayúsculas el primer carácter:

• ... en cada palabra para lograr el estilo UpperCamelCase, o
• ... en cada palabra excepto la primera en lograr el estilo lowerCamelCase

4. Finalmente, concatenar todas las palabras en un solo identificador



Tenga en cuenta que el caso de las palabras originales se ignora casi por completo.



Ejemplos:



* Permitido pero no recomendado.



Nota : algunas palabras en inglés usan un guión de manera ambigua: por ejemplo, tanto "nonempty" como "non-empty" son correctos, por lo que los nombres de método checkNonempty y checkNonEmpty también son correctos.

6. Práctica de programación

6.1 Utilice siempre la anotación @Override

El método está marcado con la anotación @Override siempre que se anula. Esto se aplica tanto a un método de una clase descendiente que anula un método de una clase principal como a un método de interfaz que anula un método de una superinterfaz.



Excepción : la anotación se puede omitir si el método principal está marcado con la anotación @Deprecated.

6.2 No ignore las excepciones detectadas

Es muy raro que haya situaciones en las que no necesite realizar ninguna acción en respuesta a una excepción detectada (una solución típica es registrarla o, si se considera "imposible", lanzar la excepción como un AssertionError).



A continuación se muestra un ejemplo con un comentario explicativo sobre cuándo es realmente apropiado no realizar ninguna acción en el bloque de captura:

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

Excepción : en las pruebas, una excepción detectada puede ignorarse y descomentarse si se espera el nombre de la prueba o si el nombre comienza con esperado. El siguiente es un modismo muy común que muestra que el código bajo prueba arroja una excepción del tipo esperado, por lo que no se necesitan comentarios aquí:

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

6.3 Para miembros estáticos, use el nombre de la clase

Es necesario acceder a un miembro de una clase estática a través del nombre de la clase, y no por referencia a un objeto de clase o por una expresión que devuelva este objeto:

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

6.4 No utilice finalizadores

Es extremadamente raro que necesite anular el método Object.finalize.



Pista :



no hagas esto. Si realmente lo necesita, primero lea y comprenda a fondo el elemento 7 de Effective Java, Evite los finalizadores, y luego no lo haga.

7. Javadoc

7.1 Formateo

7.1.1 Forma principal

El formateo simple de bloques Javadoc sigue este ejemplo:

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

... o en una línea:

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

La forma simple es siempre aplicable. El formulario de una sola línea se puede aplicar cuando todo el bloque Javadoc (incluidos los marcadores de comentarios) puede caber en una línea. Tenga en cuenta que esto solo es aplicable cuando el bloque no contiene etiquetas como @return.

7.1.2 Párrafos

Una línea en blanco, es decir, una línea que contiene solo un asterisco inicial alineado (*), aparece entre párrafos y antes del grupo de etiquetas de bloque, si lo hubiera. Cada párrafo, excepto el primero, contiene un <p> inmediatamente antes de la primera palabra, sin un espacio después.

7.1.3 Bloquear etiquetas

Todas las etiquetas de bloque están en este orden: @param, @return, @throws, @deprecated, y estos cuatro tipos nunca están presentes con descripciones vacías. Si una etiqueta de bloque no cabe en una línea, las líneas de continuación se sangran cuatro (o más) espacios desde @.

7.2 Fragmento final

Cada bloque de Javadoc comienza con un breve fragmento de resumen. Este fragmento es muy importante: es el único texto que aparece en un contexto específico, como índices de clases y métodos.



Este fragmento es un sustantivo o una frase verbal, no una oración completa. No comienza con A {@code Foo} es un ... o Este método devuelve ..., ni forma una oración afirmativa completa como Save the record. Sin embargo, este pasaje se escribe con mayúscula y se puntúa como si fuera una oración completa.



Sugerencia : es un error común escribir un Javadoc simple como / ** @return the customer ID * /. Esto es incorrecto y debe corregirse a / ** Devuelve el ID de cliente. * /.

7.3 Cuándo se aplica Javadoc

Javadoc está presente en al menos todas las clases públicas y todos los miembros públicos y protegidos de dicha clase, excepto en algunos casos, que se describen a continuación.

Puede haber un Javadoc adicional, como se explica en la Sección 7.3.4, Javadoc opcional.

7.3.1 Excepción: métodos que se describen a sí mismos

Javadoc es opcional para métodos simples y obvios como getFoo en los casos en los que realmente no puede decir más que "Devuelve foo".



Importante : No es apropiado referirse a esta excepción para justificar la omisión de información relevante que el lector general pueda necesitar.



Por ejemplo, para un método llamado getCanonicalName, no omita la documentación (con la razón de que el nombre del método solo dice / ** Devuelve el nombre canónico. * /) Si la persona promedio que lee el código ni siquiera sospecha lo que significa el término "nombre canónico" !

7.3.2 Excepción: Anular

El Javadoc no siempre acompaña a un método que anula un método de una superclase (o superinterfaz).

7.3.4 Javadoc opcional

Javadoc acompaña a otras clases y miembros según sea necesario o deseado.



Siempre que se usa un comentario de implementación para definir el propósito general o el comportamiento de una clase o miembro, ese comentario se escribe como Javadoc (usando / **).



El Javadoc opcional no tiene que seguir las reglas de formato de las Secciones 7.1.2, 7.1.3 y 7.2, aunque esto, por supuesto, se recomienda.



Esta traducción también está disponible en nuestro blog.