1 Introducción

Este documento sirve como la definición completa de los estándares de codificación de Google para código fuente en el Lenguaje de programación Java™. Un archivo fuente Java se describe como un estilo de Google si y solo si se adhiere a las reglas de este documento.

Al igual que otras guías de estilo de programación, los problemas cubiertos abarcan no solo cuestiones estéticas de los patrones, sino también otros tipos de convenciones o estándares de codificación. Sin embargo, este documento se centra principalmente en las reglas estrictas y rápidas que seguimos universalmente, y evita dar consejos que no son claramente aplicables (ya sea por humanos o herramientas).

1.1 Notas terminológicas

En este documento, a menos que se aclare lo contrario:

1. El término clase se usa inclusivamente para referirse a una clase «ordinaria», clase de enumeración, interfaz o tipo de anotación (@interface).
2. El término miembro (de una clase) se usa inclusivamente para referirse a una clase, campo, método o constructor anidados; es decir, todos los contenidos de nivel superior de una clase excepto inicializadores y comentarios.
3. El término comentario siempre se refiere a los comentarios de implementación. No usamos la frase «comentarios de documentación», sino el término común «Javadoc».»

Otras» notas terminológicas » aparecerán ocasionalmente en todo el documento.

1.2 Notas de guía

El código de ejemplo de este documento no es normativo. Es decir, aunque los ejemplos están al estilo de Google, es posible que no ilustren la única forma elegante de representar el código. Las opciones de formato opcionales tomadas en los ejemplos no deben aplicarse como reglas.

2 Conceptos básicos del archivo de origen

2.1 Nombre de archivo

El nombre del archivo de origen consiste en el nombre que distingue entre mayúsculas y minúsculas de la clase de nivel superior que contiene(de la cual hay exactamente una), más la extensión.java.

2.2 Codificación de archivos: UTF-8

Los archivos fuente están codificados en UTF-8.

2.3 Caracteres especiales

2.3.1 Caracteres de espacios en blanco

Aparte de la secuencia del terminador de línea, el carácter de espacio horizontal ASCII (0x20) es el único carácter de espacio en blanco que aparece en cualquier lugar de un archivo de origen. Esto implica que:

1. All other whitespace characters in string and character literals are escaped.
2. Tab characters are not used for indentation.

2.3.2 Special escape sequences

For any character that has a special escape sequence(\b\t\n\f\r\"\' and\\), that sequenceis used rather than the corresponding octal(e.g. \012) or Unicode(e.g. \u000a) escape.

2.3.3 Caracteres no ASCII

Para los caracteres no ASCII restantes, se utiliza el carácter Unicode real(por ejemplo, ∞) o el escape Unicode equivalente(por ejemplo, \u221e). La elección solo depende de lo que hace que el código sea más fácil de leer y entender, aunque Unicode escapa de los literales de cadena y los comentarios externos se desaconsejan.

Sugerencia: En el caso de escape Unicode, y ocasionalmente incluso cuando se utilizan caracteres de código unitario real, un comentario explicativo puede ser muy útil.

Ejemplos:

Ejemplo	Discusión
String unitAbbrev = "μs";	lo Mejor: perfectamente claro, incluso sin un comentario.
String unitAbbrev = "\u03bcs"; // "μs"	Permitidos, pero no hay ninguna razón para ello.
String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"	Permitidos, pero torpe y propenso a errores.
String unitAbbrev = "\u03bcs";	Buenos: el lector no tiene idea de lo que es esto.
return '\ufeff' + content; // byte order mark	Buenas: utilice escapes para caracteres no imprimibles y comente si es necesario.

Consejo: Nunca haga que su código sea menos legible simplemente por temor a que algunos programas no manejen correctamente caracteres que no sean ASCII. Si eso sucede, esos programas se rompen y deben arreglarse.

3 Estructura del archivo de origen

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

3.1 Información de licencia o derechos de autor, si está presente

Si la información de licencia o derechos de autor pertenece a un archivo, pertenece aquí.

3.2 Instrucción Package

La instrucción package no está envuelta en línea. El límite de columna (Sección 4.4, Límite de columna: 100) no se aplica a las instrucciones de paquete.

3.3 instrucciones de Importación

3.3.1 No se utilizan importaciones de comodines

Las importaciones de comodines, estáticas o de otro tipo.

3.3.2 Sin envoltura de línea

Las instrucciones de importación no están envueltas en línea. El límite de columnas (Sección 4.4,Límite de columnas: 100) no se aplica a las declaraciones de importación.

3.3.3 Orden y espaciado

Las importaciones se ordenan de la siguiente manera:

1. Todas las importaciones estáticas en un solo bloque.
2. Todas las importaciones no estáticas en un solo bloque.

Si hay importaciones estáticas y no estáticas, una sola línea en blanco separa los dos bloques. No hay otras líneas en blanco entre las declaraciones de importación.

Dentro de cada bloque, los nombres importados aparecen en orden de clasificación ASCII. (Nota: esto no es lo mismo que las instrucciones de importación que están en orden de clasificación ASCII, ya que ‘.»clases anteriores»;».)

3.3.4 No hay importación estática para clases

La importación estática no se utiliza para clases anidadas estáticas. Se importan con importaciones normales.

Declaración de clase 3.4

3.4.1 Exactamente una declaración de clase de nivel superior

Cada clase de nivel superior reside en un archivo fuente propio.

3.4.2 Orden de los contenidos de la clase

El orden que elija para los miembros e inicializadores de su clase puede tener un gran efecto en la capacidad de aprendizaje. Sin embargo, no hay una sola receta correcta para hacerlo; las diferentes clases pueden ordenar sus contenidos de diferentes maneras.

Lo importante es que cada clase use algún orden lógico, que su mantenedor podría explicar si se le pregunta. Por ejemplo, los nuevos métodos no solo se agregan habitualmente al final de la clase, ya que eso produciría un orden «cronológico por fecha de adición», que no es un orden lógico.

3.4.2.1 Sobrecargas: nunca dividir

Cuando una clase tiene varios constructores o varios métodos con el mismo nombre, estos aparecen consecutivamente, sin otro código entre ellos (ni siquiera miembros privados).

4 Formato

Nota terminológica: la construcción tipo bloque se refiere al cuerpo de una clase, método o constructor. Tenga en cuenta que, según la Sección 4.8.3.1, los inicializadores onarray, cualquier inicializador de matriz puede tratarse opcionalmente como si fuera una construcción similar a un bloque.

4.1 Aparatos ortopédicos

4.1.1 Se usan llaves donde se usan llaves opcionales

conifelsefordo y, incluso cuando el cuerpo está vacío o contiene una sola sentencia.

4.1.2 Bloques no vacíos: K & Estilo R

Las llaves siguen el estilo Kernighan y Ritchie («llaves egipcias») para bloques no vacíos y construcciones similares a bloques:

• Sin saltos de línea antes de la llave de apertura.
• Salto de línea después de la abrazadera de apertura.
• Salto de línea antes de la abrazadera de cierre.
• Salto de línea después de la llave de cierre, solo si esa llave termina una instrucción o termina el cuerpo de un método, constructor o clase con nombre. Por ejemplo, no hay un salto de línea después de la llave si va seguida de else o una coma.

Ejemplos:

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,Clases de enumeración se dan algunas excepciones para las clases de enumeración.

4.1.3 bloques Vacíos: puede ser conciso

Un bloque vacío o una construcción similar a un bloque puede estar en el estilo K & R (como se describe en la sección 4.1.2). Alternativamente, puede cerrarse inmediatamente después de que se abra, sin caracteres ni saltos de línea entre ellos({}), a menos que sea parte de una instrucción de varios bloques (una que contenga directamente varios bloques:if/else otry/catch/finally).

Ejemplos:

 // This is acceptable void doNothing() {} // This is equally acceptable void doNothingElse() { }

 // This is not acceptable: No concise empty blocks in a multi-block statement try { doSomething(); } catch (Exception e) {}

4.2 Bloque de sangría: +2 espacios

Cada vez que se abre un nuevo bloque o construcción similar a un bloque, la sangría aumenta en dos espacios. Cuando el bloque termina, la sangría vuelve al nivel de sangría anterior. El nivel de sangría se aplica tanto al código como a los comentarios en todo el bloque. (Consulte el ejemplo de la Sección 4.1.2, Bloques no vacíos: K & Estilo R.)

4.3 Una instrucción por línea

Cada instrucción va seguida de un salto de línea.

4.4 Límite de columnas: 100

El código Java tiene un límite de columnas de 100 caracteres. Un «carácter» significa cualquier punto de código Unicode.Excepto como se indica a continuación, cualquier línea que exceda este límite debe estar envuelta en línea, como se explica en la sección 4.5, Envoltura de línea.

Cada punto de código Unicode cuenta como un carácter, incluso si su ancho de pantalla es mayor o menor. Por ejemplo, si utiliza caracteres de ancho completo, puede optar por ajustar la línea antes de lo estrictamente requerido por esta regla.Excepciones

: Líneas

1. donde no es posible obedecer el límite de columna (por ejemplo, una URL larga en Javadoc o una referencia de método JSNI larga).instrucciones
2. package y import (consulte las secciones 3.2 Instrucciones de paquete y 3.3 Instrucciones de importación).
3. Líneas de comandos en un comentario que se puede cortar y pegar en un shell.

4.5 Envoltura de líneas

Nota terminológica: Cuando el código que de otro modo podría ocupar legalmente una sola línea se divide en varias líneas, esta actividad se denomina envoltura de líneas.

No hay una fórmula completa y determinista que muestre exactamente cómo envolver la línea en cada situación. Muy a menudo hay varias formas válidas de envolver la misma pieza de código.

Nota: Mientras que la razón típica para el ajuste de línea es evitar el desbordamiento del límite de columna, incluso el código que de hecho encajaría dentro del límite de columna puede estar envuelto en línea a discreción del autor.

Consejo: Extraer un método o una variable local puede resolver el problema sin necesidad de ajustar la línea.

4.5.1 Dónde romper

La directiva principal del ajuste de líneas es: prefiera romperse a un nivel sintáctico más elevado. También:

1. Cuando se rompe una línea en un operador sin asignación, el salto viene antes del símbolo. (Tenga en cuenta que esta no es la misma práctica que se usa en el estilo de Google para otros lenguajes, como C++ y JavaScript.)
   • Esto también se aplica a los siguientes símbolos «tipo operador»:
     • el separador de puntos (.)
     • los dos puntos de una referencia de método (::)
     • un ampersand en un encuadernado de tipo (<T extends Foo & Bar>)
     • una tubería en un bloque de captura (catch (FooException | BarException e)).
2. Cuando una línea se rompe en un operador de asignación el descanso normalmente viene después del símbolo, pero de cualquier manera es aceptable.
   • Esto también se aplica a los dos puntos» tipo operador de asignación»en una instrucción mejorada for («foreach»).
3. Un nombre de método o constructor permanece unido al paréntesis abierto (() que le sigue.
4. Una coma (,) permanece adjunta al token que la precede.
5. Una línea nunca se rompe adyacente a la flecha en una lambda, excepto que una ruptura puede venir inmediatamente después de la flecha si el cuerpo de la lambda consiste en una sola expresión sin corchete. Ejemplos:

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

Nota: El objetivo principal de la envoltura de líneas es tener clearcode, no necesariamente código que quepa en el menor número de líneas.

4.5.2 Sangría de líneas de continuación al menos +4 espacios

Al envolver líneas, cada línea después de la primera (cada línea de continuación) se sangra al menos +4 de la línea original.

Cuando hay varias líneas de continuación, la sangría puede variar más allá de +4 según lo deseado. En general, dos líneas de continuación utilizan el mismo nivel de sangría si y solo si comienzan con elementos sintácticamente paralelos.

La sección 4.6.3 sobre alineación horizontal se refiere a la práctica desaconsejada de utilizar un número variable de espacios para alinear ciertos símbolos con líneas anteriores.

4.6 Espacios en blanco

4.6.1 Espacios en blanco verticales

Siempre aparece una sola línea en blanco:

1. Entre miembros consecutivos o inicializadores de una clase: campos, constructores, métodos, clases anidadas, inicializadores estáticos e inicializadores de instancias. Excepción
   • : Una línea en blanco entre dos campos consecutivos (sin otro código entre ellos) es opcional. Estas líneas en blanco se utilizan según sea necesario para crear agrupaciones lógicas de campos.
   • Excepción: Las líneas en blanco entre constantes de enumeración se tratan en la sección 4.8.1.
2. Según lo requieran otras secciones de este documento (como la Sección 3, Estructura del archivo de origen, y la Sección 3.3, Instrucciones de importación).

Una sola línea en blanco también puede aparecer en cualquier lugar que mejore la legibilidad, por ejemplo, entre declaraciones para organizar el código en subsecciones lógicas. Una línea en blanco antes del primer miembro o inicializador, o después del último miembro o inicializador de la clase, no se alienta a nordiscouraged.

Se permiten varias líneas en blanco consecutivas, pero nunca se requieren (o se recomienda).

4.6.2 Espacios en blanco horizontales

Más allá de donde lo requiera el lenguaje u otras reglas de estilo, y aparte de literales, comentarios Yjavadoc, un solo espacio ASCII también aparece solo en los siguientes lugares.

1. Separando cualquier palabra reservada, como iffor o catch, de un paréntesis abierto (() que le sigue en esa línea li>
2. Separar cualquier palabra reservada, como elseo catch, de una llave rizada de cierre (}) que la precede en esa línea
3. Antes de cualquier llave rizada abierta ({), con dos excepciones:
   • @SomeAnnotation({a, b}) (sin espacio)
   • String x = {{"foo"}}; (no se requiere espacio entre {{, por el punto 8 de los de abajo)
4. En ambos lados de cualquier binario o ternario operador. Esto también se aplica a los siguientes símbolos «tipo operador»:
   • el ampersand en un tipo conjuntivo enlazado: <T extends Foo & Bar>
   • la tubería para un bloque de captura que maneja múltiples excepciones: catch (FooException | BarException e)
   • el colon (:) en un aumento de for («foreach») declaración
   • la flecha en una expresión lambda: (String str) -> str.length()

   pero no

   • los dos signos de dos puntos (::) de un método de referencia, que se escribe como Object::toString
   • el punto separador (.), que se escribe como object.toString()
5. Después de ,:; o el paréntesis de cierre ()) de un reparto
6. En ambos lados de la doble barra (//) que comienza un fin-de-línea de comentario. Aquí, se permiten varios espacios, pero no se requieren.
7. Entre el tipo y la variable de una declaración: List<String> list
8. Opcional justo dentro de las dos llaves de un inicializador de matriz
   • new int {5, 6} y new int { 5, 6 } son ambos válidos
9. Entre una anotación de tipo y o ....

Esta regla nunca se interpreta como que requiere u prohíbe espacio adicional al principio o al final de una línea; solo se refiere al espacio interior.

4.6.3 Alineación horizontal: nunca se requiere

Nota terminológica: La alineación horizontal es la práctica de agregar un número variable de espacios adicionales en su código con el objetivo de hacer que ciertos tokens aparezcan directamente debajo de otros tokens en líneas anteriores.

Esta práctica está permitida, pero nunca es requerida por el estilo de Google. Ni siquiera es necesario mantener la alineación horizontal en lugares donde ya se utilizó.

Aquí hay un ejemplo sin alineación, luego usando alineación:

private int x; // this is fineprivate Color color; // this tooprivate int x; // permitted, but future editsprivate Color color; // may leave it unaligned

Consejo: La alineación puede ayudar a la legibilidad, pero crea problemas para el mantenimiento futuro. Considere un cambio futuro que necesita tocar una sola línea. Este cambio puede dejar el formato anteriormente agradable destrozado, y eso está permitido. Con más frecuencia, solicita al codificador (tal vez a usted) que también ajuste los espacios en blanco en las líneas cercanas, lo que posiblemente activará una serie de reformateos en cascada. Ese cambio de una línea ahora tiene un «radio de explosión».»En el peor de los casos, esto puede resultar en un trabajo sin sentido, pero en el mejor de los casos todavía corrompe la información histórica de las versiones, ralentiza a los revisores y exacerba los conflictos de fusión.

4.7 Paréntesis de agrupación: recomendado

Los paréntesis de agrupación opcionales se omiten solo cuando el autor y el revisor están de acuerdo en que no hay una posibilidad razonable de que el código se malinterprete sin ellos, ni habrían hecho que el código fuera más fácil de leer. No es razonable asumir que cada lector tiene memorizada toda la tabla de precedencia de Javaoperator.

4.8 Construcciones específicas

4.8.1 Clases de enumeración

Después de cada coma que sigue a una constante de enumeración, un salto de línea es opcional. También se permiten líneas blancas adicionales (generalmente solo una). Esta es una posibilidad:

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

Una clase de enumeración sin métodos y sin documentación sobre sus constantes puede formarse opcionalmente como si fuera un inicializador de matriz (consulte la Sección 4.8.3.1 inicializadores de un array).

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

Dado que las clases enum son clases, se aplican todas las demás reglas para dar formato a las clases.

4.8.2 Declaraciones de variables

4.8.2.1 Una variable por declaración

Cada declaración de variable (campo o local) declara solo una variable: declaraciones comoint a, b; no se utilizan.

Excepción: Se aceptan declaraciones de múltiples variables en el encabezado de un buclefor.

4.8.2.2 Declarado cuando sea necesario

Las variables locales no se declaran habitualmente al inicio de su construcción conteningblock o similar a un bloque. En su lugar, las variables locales se declaran cerca del punto en el que se utilizan por primera vez (dentro de lo razonable), para minimizar su ámbito. Las declaraciones de variables locales suelen tener inicializadores o se inicializan inmediatamente después de la declaración.

4.8.3 Matrices

4.8.3.1 Inicializadores de matrices: puede ser»similar a un bloque»

Cualquier inicializador de matriz puede formatearse opcionalmente como si se tratara de una «construcción similar a un bloque».»Por ejemplo, los siguientes son válidos (no una exhaustivelist):

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

4.8.3.2 No C-estilo declaraciones de matriz

Los corchetes forma parte del tipo, no la variable:String args, noString args.

4.8.4 Instrucciones de conmutación

Terminología Nota: Dentro de las llaves del bloque aswitch hay uno o más grupos de instrucciones. Cada grupo de sentencias consta de una o más etiquetas de conmutación (ya sea case FOO: odefault:), seguidas de una o más sentencias (o, para el último grupo de sentencias, cero o más sentencias).

4.8.4.1 Sangría

Al igual que con cualquier otro bloque, el contenido de un bloque de conmutador tiene sangría +2.

Después de una etiqueta de interruptor, hay un salto de línea, y el nivel de sangría aumenta +2, exactamente como si se estuviera abriendo un bloque. La siguiente etiqueta de interruptor vuelve al nivel de sangría anterior, como si un bloque se hubiera cerrado.

4.8.4.2 Caída: comentado

Dentro de un bloque de conmutadores, cada grupo de instrucciones termina abruptamente (con una excepciónbreakcontinuereturn o lanzada), o está marcado con un comentario para indicar que la ejecución continuará o podría continuar en el siguiente grupo de instrucciones. Cualquier comentario que comunique la idea de falla es suficiente (típicamente// fall through). Este comentario especial no es necesario en el último grupo de instrucciones del bloque switch. Ejemplo:

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

Observe que no se necesita ningún comentario después de case 1:, solo al final del grupo de instrucciones.

4.8.4.3 El caso default está presente

Cada instrucción de switch incluye un grupo de estados default, incluso si no contiene código.Excepción

: Una instrucción switch para un tipo enum puede omitir el grupo de instrucciones default, si incluye casos explícitos que cubren todos los valores posibles de ese tipo. Esto permite que los IDE u otras herramientas de análisis estadístico emitan una advertencia si se omitieron casos.

4.8.5 Anotaciones

Las anotaciones que se aplican a una clase, método o constructor aparecen inmediatamente después del bloque de documentación, y cada anotación se muestra en una línea propia (es decir, una anotación por línea). Estos saltos de línea no constituyen envoltura de línea (Sección 4.5, Envoltura de línea), por lo que el nivel de sangría no aumenta. Ejemplo:

@Override@Nullablepublic String getNameIfPresent() { ... }

Excepción: En su lugar, una sola anotación sin parámetros puede aparecer junto con la primera línea de la firma, por ejemplo:

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

Las anotaciones que se aplican a un campo también aparecen inmediatamente después del bloque de documentación, 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 específicas para formatear anotaciones en parámetros, variables locales o tipos.

En esta sección se abordan los comentarios sobre la implementación. Javadoc se aborda por separado en la sección 7, Javadoc.

Cualquier salto de línea puede ir precedido de espacios en blanco arbitrarios seguidos de un comentario de implementación.Tal comentario hace que la línea no esté en blanco.

4.8.6.1 Estilo de comentario de bloque

Los comentarios de bloque están sangrados al mismo nivel que el código circundante. Pueden estar en el estilo/* ... */ o// .... Para comentarios de varias líneas/* ... */, las líneas siguientes deben comenzar con*alineados con * en la línea anterior.

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

Los comentarios no están encerrados en cajas dibujadas con asteriscos u otros caracteres.

Consejo: Al escribir comentarios de varias líneas, use el estilo/* ... */ si desea formateadores de código automáticos que envuelvan las líneas cuando sea necesario (estilo de párrafo). La mayoría de los formateadores no vuelven a envolver líneas en bloques de comentarios de estilo// ....

Modificadores 4.8.7

Los modificadores de clase y miembro, cuando están presentes, aparecen en el pedido 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

longLos literales enteros con valor usan un sufijo L, nunca en minúsculas (para evitar confusiones con el dígito 1). Por ejemplo, 3000000000Len vez de 3000000000l.

5 Nomenclatura

5.1 Las reglas comunes a todos los identificadores

Los identificadores utilizan solo letras y dígitos ASCII y,en un pequeño número de casos que se indican a continuación, guiones bajos. Por lo tanto, cada nombre de identificador válido coincide con la expresión regular\w+ .

In Google Style, special prefixes or suffixes are not used. For example, thesenames are not Google Style: name_mNames_name and kName.

5.2 Rules by identifier type

5.2.1 Package names

Package names are all lowercase, with consecutive words simply concatenated together (nounderscores). For example, com.example.deepspace, notcom.example.deepSpace orcom.example.deep_space.

5.2.2 Class names

Class names are written in UpperCamelCase.

Los nombres de clase suelen ser sustantivos o frases nominales. Por ejemplo,Character oImmutableList. Los nombres de interfaz también pueden ser sustantivos o frases de nombres (por ejemplo, List), pero a veces pueden ser en su lugar adjetivos o frases adjetivas (por ejemplo,Readable).

No hay reglas específicas o incluso convenciones bien establecidas para nombrar tipos de anotación.

Las clases de prueba se nombran comenzando con el nombre de la clase que están probando y terminando con Test. Por ejemplo,HashTest oHashIntegrationTest.

5.2.3 Los nombres de los métodos

Los nombres de los métodos se escriben en Minicamelcase.

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

Los guiones bajos pueden aparecer en los nombres de los métodos de prueba de JUnit para separar los componentes lógicos del nombre, con cada componente escrito en lowerCamelCase.Un patrón típico es <methodUnderTest>_<state>,por ejemplo: pop_emptyStack. No hay una manera correcta de nombrar los métodos de prueba.

5.2.4 Nombres de constantes

Los nombres de constantes usan CONSTANT_CASE : todas las letras mayúsculas, con cada palabra separada de la siguiente por un solo guion bajo. Pero, ¿qué es una constante, exactamente?

Las constantes son campos finales estáticos cuyo contenido es profundamente inmutable y cuyos métodos tienen efectos secundarios nodetectables. Esto incluye primitivas, Cadenas, tipos inmutables y colecciones inmutables de tipos inmutables. Si cualquiera de los estados observables de la instancia puede cambiar, no es constante. La mera intención de nunca mutar el objeto no es suficiente. Ejemplos:

// Constantsstatic 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 immutablestatic final SomeMutableType EMPTY_ARRAY = {};enum SomeEnum { ENUM_CONSTANT }// Not constantsstatic 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"};

Estos nombres son típicamente sustantivos o frases nominales.

5.2.5 Los nombres de campo no constantes

Los nombres de campo no constantes (estáticos o de otro tipo) se escriben en el caso de la cámara baja.

Estos nombres son típicamente sustantivos o frases nominales. Por ejemplo,computedValues oindex.

5.2.6 Los nombres de parámetros

Los nombres de parámetros se escriben en lowerCamelCase.

Se deben evitar los nombres de parámetros de un carácter en los métodos públicos.

5.2.7 Nombres de variables locales

Los nombres de variables locales se escriben en minúsculas.

Incluso cuando se trata de variables finales e inmutables, las variables locales no se consideran constantes, y no deben diseñarse como constantes.

5.2.8 Nombres de variables de tipo

Cada variable de tipo se nombra en uno de dos estilos:

• Una sola letra mayúscula, opcionalmente seguida de un solo número (como ETXT2)
• Un nombre en la forma utilizada para las clases (consulte la sección 5.2.2, Nombres de clases), seguido de la letra mayúscula T (ejemplos: RequestTFooBarT).

5.3 Camel case: definido

A veces hay más de una forma razonable de convertir una frase en inglés en camel case, como cuando hay acrónimos o construcciones inusuales como» IPv6 «o» iOS » presentes. Para mejorar la predictibilidad, el estilo de Google especifica el siguiente esquema (casi) determinista.

Comenzando con la forma en prosa del nombre:

1. Convierta la frase a ASCII simple y elimine cualquier apóstrofo. Por ejemplo, el» algoritmo de Müller «podría convertirse en»algoritmo de Mueller».
2. Divida este resultado en palabras, dividiéndolo en espacios y en cualquier puntuación restante (típicamente guiones).
   • Recomendado :si alguna palabra ya tiene una apariencia de caja de camello convencional de uso común, divídala en sus partes constituyentes (por ejemplo, «AdWords» se convierte en «palabras de anuncio»). Tenga en cuenta que una palabra como «iOS» no está en realidad en el caso camel per se; desafía cualquier convención, por lo que esta recomendación no se aplica.
3. Ahora todo en minúsculas (incluidas las siglas), luego en mayúsculas solo el primer carácter de:
   • … cada palabra, para producir una caja de camello superior, o
   • … cada palabra, excepto la primera, para obtener un caso de camello inferior
4. Finalmente, une todas las palabras en un único identificador.

Tenga en cuenta que la carcasa de las palabras originales se ignora casi por completo. Ejemplos:

Prose form	Correct	Incorrect
«XML HTTP request»	XmlHttpRequest	XMLHTTPRequest
«new customer ID»	newCustomerId	newCustomerID
«inner stopwatch»	innerStopwatch	innerStopWatch
«supports IPv6 on iOS?»	supportsIpv6OnIos	supportsIPv6OnIOS
«YouTube importer»	YouTubeImporter YoutubeImporter*

*Acceptable, but not recommended.

Note: Some words are ambiguously hyphenated in the Englishlanguage: for example «nonempty» and «non-empty» are both correct, so the method namescheckNonempty andcheckNonEmpty are likewise both correct.

6 Programming Practices

6.1 @Override: siempre usado

Un método está marcado con la anotación @Override siempre que sea legal. Esto incluye un método de clase que anula un método de superclase, un método de clase que implementa un método de interfaz y un método de interfaz que vuelve a definir un método de superinterfaz.

Excepción:@Override puede omitirse cuando el padre es el método@Deprecated.

6.2 Excepciones capturadas: no ignoradas

Excepto como se indica a continuación, es muy raro que no se haga nada en respuesta a una excepción de caughtexception. (Las respuestas típicas son registrarlo, o si se considera «imposible», repensarlo como unAssertionError.)

Cuando realmente es apropiado no realizar ninguna acción en un bloque de captura, la razón por la que esto se justifica se explica en un comentario.

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 sin comentarios si su nombre es o comienza con expected. El siguiente es un modismo muy común para asegurar que el código bajo prueba arroje una excepción del tipo esperado, por lo que un comentario es innecesario aquí.

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

6.3 Miembros estáticos: calificados usando clase

Cuando una referencia a un miembro de clase estático debe estar calificada, se califica con el nombre de esa clase, no con una referencia o expresión del tipo de esa clase.

Foo aFoo = ...;Foo.aStaticMethod(); // goodaFoo.aStaticMethod(); // badsomethingThatYieldsAFoo().aStaticMethod(); // very bad

6.4 Finalizadores: no se usa

es muy raro para reemplazar Object.finalize.

Consejo: no lo hagas. Si es absolutamente necesario, primero lea y comprenda el Elemento 7 de Java efectivo, «Evite los finalizadores», con mucho cuidado, y luego no lo haga.

7 Javadoc

7.1 Formateo

7.1.1 Formulario general

El formato básico de los bloques Javadoc es como se ve en este ejemplo:

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

… o en este ejemplo de una sola línea:

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

El formulario básico siempre es aceptable. La forma de una sola línea puede sustituirse cuando la totalidad del bloque Javadoc (incluidos los marcadores de comentarios) puede caber en una sola línea. Tenga en cuenta que esto solo se aplica cuando no hay etiquetas de bloque como @return.

7.1.2 Párrafos

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

7.1.3 Etiquetas de bloque

Cualquiera de las «etiquetas de bloque» estándar que se utilizan aparecen en el orden @param@return@throws@deprecated, y estos cuatro tipos nunca aparecen con una descripción vacía. Cuando una etiqueta de bloque no cabe en una sola línea, las líneas de continuación están sangradas cuatro (o más) espacios desde la posición de @.

7.2 El fragmento de resumen

Cada bloque Javadoc comienza con un breve fragmento de resumen. Este fragmento es muy importante: es la única parte del texto que aparece en ciertos contextos, como los índices de clase y método.

Este es un fragmento, una frase nominal o verbal, no una oración completa. Doesnot comienzan con A {@code Foo} is a... oThis method returns..., ni tampoco constituyen un imperativo sentencelike Save the record.. Sin embargo, el fragmento se escribe en mayúscula y se escribe como si fuera una oración completa.

Consejo: Un error común es escribir Javadoc simple en el formulario/** @return the customer ID */. Esto es incorrecto, y debería cambiarse a /** Returns the customer ID. */.

7.3 Donde se usa Javadoc

Como mínimo, Javadoc está presente para cada clasepublic, y cada miembropublic oprotected de dicha clase, con algunas excepciones enumeradas a continuación.

También puede haber contenido Javadoc adicional, como se explica en la Sección 7.3.4, Javadoc no obligatorio.

7.3.1 Excepción: métodos autoexplicativos

Javadoc es opcional para métodos «simples y obvios» comogetFoo, en casos en los que realmente no hay nada más que valga la pena decir que «Devuelve el foo».

Importante: no es apropiado citar esta excepción para justificar la información relevante que un lector típico podría necesitar conocer. Por ejemplo, para un método con el nombre getCanonicalName, no omita su documentación (con la justificación de que solo diría/** Returns the canonical name. */) si un lector típico puede no tener idea de lo que significa el término «nombre canónico».Excepción

7.3.2: anula

Javadoc no siempre está presente en un método que anula un método de supertipo.

7.3.4 Javadoc no obligatorio

Otras clases y miembros tienen Javadoc según sea necesario o deseado.