Guía de estilo de Google Java

Tabla de contenido

1 Introducción 4.5 Ajuste de línea

1.1 Notas terminológicas 4.6 Espacios en blanco
1.2 Notas de guía 4.7 Agrupación de paréntesis: recomendado
4.8 Construcciones específicas
2 Conceptos básicos de los archivos fuente
2.1 Nombre del archivo 5 Nombramiento
2.2 Codificación de archivos: UTF-8 5.1 Reglas comunes a todos los identificadores
2.3 Caracteres especiales 5.2 Reglas por tipo de identificador
5.3 Caso Camel: definición
3 Estructura del archivo fuente
3.1 Información sobre licencia o derechos de autor, si está presente 6 Prácticas de programación
3.2 Declaración del paquete 6.1 @Override: siempre se utiliza
3.3 Importaciones 6.2 Excepciones detectadas: no ignoradas
3.4 Declaración de clase 6.3 Miembros estáticos: calificados usando la clase
3.5 Declaración del módulo 6.4 Finalizadores: no utilizados

4 Formato 7 Javadoc
4.1 Brackets 7.1 Formato
4.2 Sangría de bloque: +2 espacios 7.2 El fragmento de resumen
4.3 Una declaración por línea 7.3 Dónde se utiliza Javadoc
4.4 Límite de columnas: 100

1 Introducción
Este documento constituye la definición completa de los estándares de codificación de Google para el código fuente en el lenguaje de programación Java™. Un archivo fuente Java se considera de estilo Google únicamente si cumple con las reglas aquí
descritas.

Al igual que otras guías de estilo de programación, los temas abordados abarcan no solo aspectos estéticos del formato, sino también otros tipos de convenciones o estándares de codificación. Sin embargo, este documento se centra principalmente en las
reglas estrictas que seguimos universalmente y evita dar consejos que no sean claramente aplicables (ya sea por personas o por herramientas).

1.1 Notas terminológicas

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

1. El término clase se utiliza de manera inclusiva para significar una clase normal, una clase de registro, una clase de enumeración, una interfaz o un tipo de anotación ( @interface ).
2. El término miembro (de una clase) se utiliza de manera inclusiva para significar una clase, un campo, un método o un constructor anidado ; es decir, todos los contenidos de nivel superior de una clase excepto los inicializadores.
3. El término comentario siempre se refiere a comentarios de implementación . No usamos la frase "comentarios de documentación", sino el término común "Javadoc".

Ocasionalmente aparecerán otras "notas terminológicas" a lo largo del documento.

1.2 Notas de guía

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

2 Conceptos básicos de los archivos fuente

2.1 Nombre del archivo

Para un archivo fuente que contiene clases, el nombre del archivo consta del nombre, que distingue entre mayúsculas y minúsculas, de la clase de nivel superior (de las cuales hay exactamente una ), más la .java extensión.

2.2 Codificación de archivos: UTF-8

Los archivos de origen están codificados en UTF-8 .

2.3 Caracteres especiales

2.3.1 Caracteres de espacio en blanco

Aparte de la secuencia de terminación de línea, el espacio horizontal ASCII ( 0x20 ) es el único espacio en blanco que aparece en un archivo fuente. Esto implica que:

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

2.3.2 Secuencias de escape especiales

Para cualquier carácter que tenga una secuencia de escape especial ( \b , \t , \n , \f , \r , \s , y ), se utiliza esa secuencia en lugar del escape octal (por ejemplo, \" ) o Unicode (por ejemplo, ). \' \\ \012 \u000a

2.3.3 Caracteres no ASCII

Para los demás caracteres no ASCII, se utiliza el carácter Unicode (p. ej., ∞ ) o el escape Unicode equivalente (p. ej., ). La elección depende únicamente de cuál facilite la lectura y comprensión del código , aunque se desaconseja el uso de escapes
Unicode fuera de literales de cadena y comentarios. \u221e

Consejo: En el caso de escape Unicode, y ocasionalmente incluso cuando se utilizan caracteres Unicode reales, un comentario explicativo puede ser muy útil.

Ejemplos:

Ejemplo Discusión

String unitAbbrev = "μs"; Lo mejor: perfectamente claro incluso sin comentarios.

String unitAbbrev = "\u03bcs"; // "μs" Permitido, pero no hay razón para hacerlo.

String unitAbbrev = "\u03bcs"; // Greek letter mu, "s" Permitido, pero incómodo y propenso a errores.

String unitAbbrev = "\u03bcs"; Pobre: el lector no tiene idea de qué es esto.

return '\ufeff' + content; // byte order mark Bueno: use escapes para caracteres no imprimibles y comente si es necesario.

Consejo: Nunca reduzca la legibilidad de su código simplemente por temor a que algunos programas no gestionen correctamente caracteres no ASCII. Si esto ocurre, esos programas están dañados y deben repararse .

3 Estructura del archivo fuente

Un archivo fuente ordinario consta de estas secciones, en orden :

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

2. Declaración de paquete
3. Importaciones
4. Exactamente una declaración de clase de nivel superior

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

Un [Link] archivo es lo mismo, pero sin la declaración de clase.

Un [Link] archivo no contiene una declaración de paquete y reemplaza la declaración de clase con una declaración de módulo, pero por lo demás sigue la misma estructura.

3.1 Información sobre 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 Declaración del paquete

La declaración del paquete no se ajusta a una línea . El límite de columnas (Sección 4.4, Límite de columnas: 100 ) no se aplica a las declaraciones de paquetes.

3.3 Importaciones

3.3.1 Sin importaciones de comodines

No se utilizan importaciones comodín ("a pedido") , estáticas o de otro tipo .

3.3.2 Sin ajuste de línea

Las importaciones no se ajustan a las líneas . El límite de columnas (Sección 4.4, Límite de columnas: 100 ) no se aplica a las importaciones.

3.3.3 Ordenamiento y espaciado

Las importaciones se ordenan de la siguiente manera:

1. Todas las importaciones estáticas en un solo grupo.

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

Si hay importaciones estáticas y no estáticas, una sola línea en blanco separa los dos grupos. No hay otras líneas en blanco entre las importaciones.

Dentro de cada grupo, los nombres importados aparecen en orden de clasificación ASCII. ( Nota: esto no es lo mismo que que las líneas de importación estén en orden de clasificación ASCII, ya que '.' se ordena antes que ';'.)

3.3.4 No hay importación estática para clases

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

3.4 Declaración de clase

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 Ordenación de los contenidos de las clases

El orden que elijas para los miembros e inicializadores de tu clase puede tener un gran impacto en la facilidad de aprendizaje. Sin embargo, no existe una única fórmula correcta para hacerlo; cada clase puede ordenar su contenido de forma distinta.

Lo importante es que cada clase utilice un orden lógico , que su responsable podría explicar si se le solicita. Por ejemplo, los nuevos métodos no se añaden habitualmente al final de la clase, ya que esto generaría un orden cronológico por fecha de adición,
que no es lógico.

[Link] Sobrecargas: nunca dividir

Los métodos de una clase que comparten el mismo nombre aparecen en un único grupo contiguo sin otros miembros intermedios. Lo mismo aplica a varios constructores. Esta regla se aplica incluso cuando modificadores como static o private difieren
entre los métodos o constructores.

3.5 Declaración del módulo

3.5.1 Ordenamiento y espaciado de las directivas del módulo

Las directivas del módulo se ordenan de la siguiente manera:

1. Todas requires las directivas en un solo bloque.

2. Todas exports las directivas en un solo bloque.
3. Todas opens las directivas en un solo bloque.
4. Todas uses las directivas en un solo bloque.
5. Todas provides las directivas en un solo bloque.

Una sola línea en blanco separa cada bloque presente.

4 Formato
Nota terminológica: Una construcción de tipo bloque se refiere al cuerpo de una clase, método, constructor o modificador. Tenga en cuenta que, según la Sección [Link] sobre inicializadores de matriz , cualquier inicializador de matriz puede tratarse
opcionalmente como una construcción de tipo bloque.

4.1 Brackets

4.1.1 Uso de llaves opcionales

Las llaves se utilizan con las declaraciones if , else , for y , incluso cuando el cuerpo está vacío o contiene solo una declaración. do while

Otras llaves opcionales, como las de una expresión lambda, siguen siendo opcionales.

4.1.2 Bloques no vacíos: estilo K y R

Las llaves siguen el estilo de Kernighan y Ritchie para bloques no vacíos y construcciones similares a bloques:

No se permite ningún salto de línea antes de la llave de apertura, excepto como se detalla a continuación.
Salto de línea después de la llave de apertura.
Salto de línea antes de la llave de cierre.
Salto de línea después de la llave de cierre, solo si esta termina una sentencia o el cuerpo de un método, constructor o clase con nombre . Por ejemplo, no hay salto de línea después de la llave si va seguida de else o una coma.

Excepción: Donde estas reglas permiten una sola sentencia terminada en punto y coma ( ; ), puede aparecer un bloque de sentencias, precedido por un salto de línea. Este tipo de bloques se suelen introducir para limitar el alcance de las variables locales.

Ejemplos:

return () -> { while ( condicion ()) {

metodo (); } };

devuelve nuevo MyClass () { @Override método público void () { if ( condition ()) { try {
algo (); } catch ( ProblemExceptione ) {
recuperar ( ) ; } } de lo contrario if ( otherCondition ()) {
somethingElse (); } de lo contrario {
lastThing (); } { int x = foo ();
frob ( x ); } } };

En la Sección 4.8.1, Clases de enumeración , se ofrecen algunas excepciones para las clases de enumeración .

4.1.3 Bloques vacíos: pueden ser concisos

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

Ejemplos:

// Esto es aceptable void doNothing () {}

// Esto es igualmente aceptable void doNothingElse () { }

// Esto no es aceptable: No hay bloques vacíos concisos en una declaración de varios bloques try {
doSomething (); } catch ( Exception e ) {}

4.2 Sangría de bloque: +2 espacios

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

4.3 Una declaración por línea

Cada afirmació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" se refiere a cualquier punto de código Unicode. Salvo lo indicado a continuación, cualquier línea que exceda este límite debe ajustarse a su tamaño original, como se explica en la
Sección 4.5, Ajuste de línea .

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

Excepciones:

1. Líneas en las que no es posible obedecer el límite de la columna (por ejemplo, una URL larga en Javadoc o una referencia de método JSNI larga).
2. package declaraciones e importaciones (véanse las secciones 3.2 Declaraciones de paquetes y 3.3 Importaciones ).
3. Contenido de los bloques de texto .
4. Líneas de comando en un comentario que se pueden copiar y pegar en un shell.
5. En las raras ocasiones en que se requieren, los identificadores muy largos pueden superar el límite de columnas. En ese caso, el formato válido para el código circundante es el generado por google-java-format .

4.5 Ajuste de línea

Nota sobre terminología: cuando el código que de otro modo ocuparía una sola línea se divide en varias líneas, esta actividad se denomina ajuste de línea .

No existe una fórmula completa y determinista que muestre exactamente cómo ajustar el código en cada situación. A menudo, existen varias maneras válidas de ajustar el código en un mismo fragmento de código.

Nota: Si bien el motivo típico para el ajuste de línea es evitar desbordar el límite de columnas, incluso el código que de hecho encajaría dentro del límite de columnas puede ajustarse 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ínea es: preferir cortar a un nivel sintáctico superior . Además:

1. Cuando una línea se divide en un operador que no es de asignación, el salto se coloca antes del símbolo. (Tenga en cuenta que esta no es la misma práctica que se utiliza en el estilo de Google para otros lenguajes, como C++ y JavaScript).
Esto también se aplica a los siguientes símbolos "similares a operadores":
el separador de puntos ( . )
los dos puntos de una referencia de método ( :: )
un ampersand en un límite de tipo ( ) <T extends Foo & Bar>
una tubería en un bloque de captura ( ). catch (FooException | BarException e)
2. Cuando se interrumpe una línea en un operador de asignación , el salto generalmente viene después del símbolo, pero de cualquier manera es aceptable.
Esto también se aplica a los dos puntos en una for declaración mejorada ("foreach").
3. Un nombre de método, constructor o clase de registro permanece adjunto al paréntesis de apertura ( ( ) que lo sigue.
4. Una coma ( , ) permanece adjunta al token que la precede.
5. Una línea nunca se interrumpe junto a la flecha en una regla lambda o switch, excepto que un salto puede ocurrir inmediatamente después de la flecha si el texto que la sigue consiste en una sola expresión sin llaves. Ejemplos:

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

Predicado < String > predicado = str ->

longExpressionInvolving ( str );

switch ( x ) { caso ColorPoint ( Color color , Punto ( int x , int y )) ->

handleColorPoint ( color , x , y ); ... }

Nota: El objetivo principal del ajuste de línea es tener un código claro, no necesariamente un código que quepa en la menor cantidad de líneas.

4.5.2 Sangrar las líneas de continuación al menos +4 espacios

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

Cuando hay varias líneas de continuación, la sangría puede ajustarse más allá de +4 según se desee. En general, dos líneas de continuación usan 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 aborda la práctica desaconsejada de utilizar una cantidad variable de espacios para alinear ciertos tokens con líneas anteriores.

4.6 Espacios en blanco

4.6.1 Espacios verticales (líneas en blanco)

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 instancia.
Excepción: Una línea en blanco entre dos campos consecutivos (sin ningún 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. Como lo requieren otras secciones de este documento (como la Sección 3, Estructura del archivo fuente y la Sección 3.3, Importaciones ).

También puede aparecer una línea en blanco en cualquier lugar que mejore la legibilidad, por ejemplo, entre sentencias para organizar el código en subsecciones lógicas. No se recomienda ni se desaconseja dejar una línea en blanco antes del primer miembro
o inicializador, o después del último miembro o inicializador de la clase.

Se permiten varias líneas en blanco consecutivas, pero nunca son obligatorias (ni recomendadas).

4.6.2 Espacios horizontales

Más allá de lo requerido por el lenguaje u otras reglas de estilo, y aparte de dentro de literales, comentarios y Javadoc, un único espacio ASCII también aparece en los siguientes lugares únicamente .

1. Separar cualquier palabra clave, como if , for o catch , de un paréntesis de apertura ( ( ) que la sigue en esa línea
2. Separar cualquier palabra clave, como else o catch , de una llave de cierre ( } ) que la precede en esa línea
3. Antes de cualquier llave abierta ( { ), con dos excepciones:
@SomeAnnotation({a, b}) (no se utiliza espacio)
String[][] x = {{"foo"}}; (no se requiere espacio entre {{ , por el punto 10 a continuación)
4. A ambos lados de cualquier operador binario o ternario. Esto también aplica a los siguientes símbolos similares a operadores:
el símbolo & que separa múltiples límites de tipos: <T extends Foo & Bar>
la tubería para un bloque catch que maneja múltiples excepciones: catch (FooException | BarException e)
los dos puntos ( : ) en una for declaración mejorada ("foreach")
la flecha en una expresión lambda: o regla de cambio: (String str) -> [Link]()
case "FOO" -> bar();
pero no
los dos puntos ( :: ) de una referencia de método, que se escribe como Object::toString
el separador de puntos ( . ), que se escribe así [Link]()
5. Después ,:; del paréntesis de cierre ( ) ) de una conversión
6. Entre cualquier contenido y una barra doble ( // ) que inicia un comentario. Se permiten varios espacios.
7. Entre la barra doble ( // ) que inicia un comentario y el texto del comentario. Se permiten varios espacios.
8. Entre el tipo y el identificador de una declaración: List<String> list
9. Opcional justo dentro de ambas llaves de un inicializador de matriz
new int[] {5, 6} y ambos son válidos new int[] { 5, 6 }
10. Entre una anotación de tipo y [] o ... .

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

4.6.3 Alineación horizontal: nunca requerida

Nota sobre terminología: La alineación horizontal es la práctica de agregar una cantidad 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 Google Style nunca la exige . Ni siquiera es necesaria para mantener la alineación horizontal donde ya se usaba.

A continuación se muestra un ejemplo sin alineación y luego se utiliza la alineación:

private int x ; // esto está bien private Color color ; // esto también

int privado x ; // permitido, pero futuras ediciones color privado color ; // pueden dejarlo sin alinear

Consejo: La alineación puede mejorar la legibilidad, pero intentar preservarla por sí misma crea problemas futuros. Por ejemplo, considere un cambio que afecta solo a una línea. Si ese cambio altera la alineación anterior, es importante **no** introducir
cambios adicionales en líneas adyacentes simplemente para realinearlas. Introducir cambios de formato en líneas que de otro modo no se verían afectadas corrompe el historial de versiones, ralentiza a los revisores y agrava los conflictos de fusión. Estas
consideraciones prácticas tienen prioridad sobre la alineación.

4.7 Agrupación de paréntesis: recomendado

Los paréntesis de agrupación opcionales se omiten solo cuando el autor y el revisor coinciden en que no hay ninguna posibilidad razonable de que el código se malinterprete sin ellos, ni habrían facilitado su lectura. No es razonable suponer que todos los
lectores tengan memorizada la tabla completa de precedencia de operadores de Java.

4.8 Construcciones específicas

4.8.1 Clases de enumeración

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

enumeración privada Respuesta {

SÍ { @Override public String toString () { return "sí" ; } },

NO ,
TAL VEZ
}

Una clase de enumeración sin métodos ni documentación sobre sus constantes puede formatearse opcionalmente como si fuera un inicializador de matriz (consulte la Sección [Link] sobre inicializadores de matriz ).

enumeración privada Traje { Tréboles , corazones , espadas , diamantes }

Dado que las clases de enumeración son clases , se aplican todas las demás reglas para formatear clases.

4.8.2 Declaraciones de variables

[Link] Una variable por declaración

Cada declaración de variable (de campo o local) declara sólo una variable: declaraciones como int a, b; no se utilizan.

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

[Link] Declarado cuando sea necesario

Las variables locales no suelen declararse al inicio de su bloque contenedor o construcción similar. En cambio, se declaran cerca del punto de su primer uso (dentro de lo razonable), para minimizar su alcance. Las declaraciones de variables locales suelen
tener inicializadores o se inicializan inmediatamente después de su declaración.

4.8.3 Matrices

[Link] Inicializadores de matriz: pueden ser "tipo bloque"

Cualquier inicializador de matriz puede formatearse opcionalmente como si fuera una construcción de bloque. Por ejemplo, los siguientes son todos válidos (esta lista no es exhaustiva):

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

[Link] No se permiten declaraciones de matrices de estilo C

Los corchetes forman parte del tipo , no de la variable: , no . String[] args String args[]

4.8.4 Sentencias y expresiones Switch

Por razones históricas, el lenguaje Java tiene dos sintaxis distintas para switch , que podemos llamar de estilo antiguo y de estilo nuevo . Los modificadores de estilo nuevo usan una flecha ( -> ) después de las etiquetas, mientras que los modificadores de
estilo antiguo usan dos puntos ( : ).

Nota terminológica: Entre las llaves de un bloque switch se encuentran una o más reglas switch (estilo nuevo); o uno o más grupos de sentencias (estilo antiguo). Una regla switch consiste en una etiqueta switch ( o ) seguida de y una expresión, bloque o . Un
grupo de sentencias consiste en una o más etiquetas switch, cada una seguida de dos puntos, y luego una o más sentencias, o, para el último grupo de sentencias, ninguna o más sentencias. (Estas definiciones coinciden con la Especificación del Lenguaje
Java, §14.11 ). case ... default -> throw

[Link] Sangría

Al igual que con cualquier otro bloque, el contenido de un bloque de conmutación tiene una sangría de +2. Cada etiqueta de conmutación comienza con esta sangría de +2.

En un cambio de nuevo estilo, una regla de cambio puede escribirse en una sola línea si sigue el estilo de Google. (No debe exceder el límite de columnas, y si contiene un bloque no vacío, debe haber un salto de línea después de { ). Se aplican las reglas
de ajuste de línea de la Sección 4.5 , incluyendo la sangría de +4 para las líneas de continuación. Para una regla de cambio con un bloque no vacío después de la flecha, se aplican las mismas reglas que para los bloques restantes: las líneas entre { y
} tienen una sangría adicional de +2 respecto a la línea con la etiqueta de cambio.

switch ( número ) { caso 0 , 1 -> handleZeroOrOne (); caso 2 ->

handleTwoWithAnExtremelyLongMethodCallThatWouldNotFitOnTheSameLine (); predeterminado -> {
logger . atInfo (). log ( "Número sorprendente %s" , número );
handleSurprisingNumber ( número ); } }

En un conmutador de estilo antiguo, los dos puntos de cada etiqueta de conmutador van seguidos de un salto de línea. Las sentencias dentro de un grupo de sentencias tienen una sangría adicional de +2.

[Link] Fall-through: comentado

Dentro de un bloque switch de estilo antiguo, cada grupo de sentencias termina abruptamente (con una excepción break , continue o return lanzada), o se marca con un comentario para indicar que la ejecución continuará o podría continuar en el
siguiente grupo de sentencias. Cualquier comentario que comunique la idea de un paso a través es suficiente (normalmente // fall through ). Este comentario especial no es necesario en el último grupo de sentencias del bloque switch. Ejemplo:

switch ( entrada ) { caso 1 : caso 2 :

prepareOneOrTwo (); // pasar al caso 3 :
handleOneTwoOrThree (); break ; predeterminado :
handleLargeNumber ( entrada ); }

Tenga en cuenta que no es necesario ningún comentario después de , solo al final del grupo de declaraciones. case 1:

En los interruptores de nuevo estilo no hay caídas.

[Link] Exhaustividad y presencia de la default etiqueta

El lenguaje Java requiere que las expresiones switch y muchos tipos de sentencias switch sean exhaustivas . Esto significa que cada valor posible que se pueda activar coincidirá con una de las etiquetas switch. Un switch es exhaustivo si tiene una
default etiqueta, pero también, por ejemplo, si el valor que se activa es una enumeración y cada valor de esta coincide con una etiqueta switch. Google Style requiere que todos los switches sean exhaustivos, incluso aquellos que el lenguaje no requiere.
Esto puede requerir agregar una default etiqueta, incluso si no contiene código.

[Link] Expresiones de cambio

Las expresiones de cambio deben ser cambios de estilo nuevo:

retorno switch ( lista . tamaño ()) { caso 0 -> "" ; caso 1 -> lista . obtenerPrimero (); predeterminado -> String . unirse ( ", " , lista ); };

4.8.5 Anotaciones

[Link] Anotaciones de uso de tipos

Las anotaciones de uso de tipo aparecen inmediatamente antes del tipo anotado. Una anotación es de uso de tipo si está metaanotada con . Ejemplo: @Target(ElementType.TYPE_USE)

final @Nullable Cadena nombre ;

público @Nullable Person getPersonByName ( String nombre );

[Link] Anotaciones de clases, paquetes y módulos

Las anotaciones que se aplican a una declaración de clase, paquete o módulo aparecen inmediatamente después del bloque de documentación, y cada anotación ocupa una línea independiente (es decir, una anotación por línea). Estos saltos de línea no
constituyen un ajuste de línea (Sección 4.5, Ajuste de línea ), por lo que no se aumenta el nivel de sangría. Ejemplos:

/** Esta es una clase. */ @Deprecated @CheckReturnValue public final class Frozzler { ... }

/** Este es un paquete. */ @Deprecated @CheckReturnValue paquete com . ejemplo . frozzler ;

/** Este es un módulo. */ @Deprecated @SuppressWarnings ( "CheckReturnValue" )

módulo com . ejemplo . frozzler { ... }

[Link] Anotaciones de métodos y constructores

Las reglas para las anotaciones en las declaraciones de métodos y constructores son las mismas que en la sección anterior . Ejemplo:

@Deprecated @Override cadena pública getNameIfPresent () { ... }

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

@Override público int hashCode () { ... }

[Link] Anotaciones de campo

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 cargador ;

[Link] Anotaciones de parámetros y variables locales

No existen reglas específicas para formatear anotaciones en parámetros o variables locales (excepto, por supuesto, cuando la anotación es una anotación de uso de tipo).

4.8.6 Comentarios

Esta sección aborda los comentarios de implementación . Javadoc se aborda por separado en la Sección 7, Javadoc .

Cualquier salto de línea puede ir precedido de un espacio arbitrario seguido de un comentario de implementación. Este comentario convierte la línea en un espacio en blanco.

[Link] Estilo de comentario de bloque

Los comentarios de bloque se sangran al mismo nivel que el código circundante. Pueden ser de /* ... */ estilo o // ... de estilo. En el caso de comentarios de varias líneas /* ... */ , las líneas subsiguientes deben comenzar * alineadas con la
* línea anterior.

/*
* Esto es // Y así /* O puedes
* ok. // es esto. * incluso hacer esto. */ */

Los comentarios no se encierran en cuadros dibujados con asteriscos u otros caracteres.

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

[Link] Comentarios de TODO

Utilice TODO comentarios para el código que sea temporal, una solución a corto plazo o suficientemente bueno pero no perfecto.

Un TODO comentario comienza con la palabra TODO en mayúsculas, dos puntos a continuación y un enlace a un recurso que contiene el contexto, idealmente una referencia a un error. Es preferible una referencia a un error, ya que se registran y se
comentan posteriormente. A continuación de este contexto, incluya una cadena explicativa con un guion - .

El propósito es tener un TODO formato consistente en el que se pueda buscar para descubrir cómo obtener más detalles.

// TODO: [Link]/12345678 - Eliminar esto después de que expire la ventana de compatibilidad 2047q4.

Evite agregar tareas pendientes que hagan referencia a un individuo o equipo como contexto:

// TODO: @yourusername - Presenta un problema y utiliza un '*' para repetir.

Si su TODO formato es "En una fecha futura hacer algo", asegúrese de incluir una fecha muy específica ("Resolver antes de noviembre de 2005") o un evento muy específico ("Eliminar este código cuando todos los clientes puedan manejar respuestas XML").

4.8.7 Modificadores

Los modificadores de clase y miembro, cuando están presentes, aparecen en el orden recomendado por la Especificación del lenguaje Java:

público protegido privado abstracto predeterminado estático final sellado no sellado

transitorio volátil sincronizado nativo strictfp

Los modificadores en requires las directivas del módulo, cuando están presentes, aparecen en el siguiente orden:

estática transitiva

4.8.8 Literales numéricos

long Los literales enteros con valor - usan un L sufijo en mayúsculas, nunca en minúsculas (para evitar confusiones con el dígito 1 ). Por ejemplo, 3000000000L en lugar de 3000000000l .

4.8.9 Bloques de texto

La apertura """ de un bloque de texto siempre se realiza en una nueva línea. Esta línea puede seguir las mismas reglas de sangría que otras construcciones o no tener sangría (comenzando en el margen izquierdo). El cierre """ se realiza en una nueva
línea con la misma sangría que la apertura """ , y puede ir seguido de código adicional en la misma línea. Cada línea de texto del bloque de texto tiene una sangría al menos igual a la apertura y el cierre """ . (Si una línea tiene una sangría mayor, el literal
de cadena definido por el bloque de texto tendrá un espacio al principio de esa línea).

El contenido de un bloque de texto puede exceder el límite de columnas .

5 Nombramiento

5.1 Reglas comunes a todos los identificadores

Los identificadores utilizan únicamente letras y dígitos ASCII y, en algunos casos (como se indica a continuación), guiones bajos. Por lo tanto, cada nombre de identificador válido se corresponde con la expresión regular \w+ .

En Google Style, no se utilizan prefijos ni sufijos especiales. Por ejemplo, estos nombres no son de Google Style: name_ , mName , s_name y kName .

5.2 Reglas por tipo de identificador

5.2.1 Nombres de paquetes y módulos

Los nombres de paquetes y módulos usan solo letras minúsculas y dígitos (sin guiones bajos). Las palabras consecutivas simplemente se concatenan. Por ejemplo, [Link] , not [Link] o [Link].deep_space .

5.2.2 Nombres de clases

Los nombres de clases se escriben en UpperCamelCase .

Los nombres de clase 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 pueden ser adjetivos o frases
adjetivales (por ejemplo, Readable ).

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

Una clase de prueba tiene un nombre que termina en Test , por ejemplo, HashIntegrationTest . Si abarca una sola clase, su nombre es el nombre de esa clase más Test , por ejemplo HashImplTest , .

5.2.3 Nombres de métodos

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

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

Los guiones bajos pueden aparecer en los nombres de los métodos de prueba de JUnit para separar los componentes lógicos del nombre, y cada componente se escribe en mayúsculas y minúsculas (por ejemplo, [ mayúsculas/min
transferMoney_deductsFromSource ...

5.2.4 Nombres de constantes

Los nombres de constantes se escriben UPPER_SNAKE_CASE en mayúsculas, con cada palabra separada por un guion bajo. Pero ¿qué es exactamente una constante?

Las constantes son campos finales estáticos cuyo contenido es completamente inmutable y cuyos métodos no tienen efectos secundarios detectables. Algunos ejemplos incluyen primitivas, cadenas, clases de valores inmutables y cualquier valor establecido
en null . Si algún estado observable de la instancia puede cambiar, no es una constante. La simple intención de no mutar nunca el objeto no es suficiente. Ejemplos:

// Constantes static final int NUMBER = 5 ; static final ImmutableList < String > NAMES = ImmutableList . of ( "Ed" , "Ann" ); static final Map < String , Integer > Ages = ImmutableMap . of ( "Ed" , 35 , "Ann

// No constantes static String nonFinal = "no final" ; final String nonStatic = "no estático" ; static final Set < String > mutableCollection = new HashSet < String >(); static final ImmutableSet < SomeMutable

Estos nombres suelen ser sustantivos o frases nominales.

5.2.5 Nombres de campos no constantes

Los nombres de campos no constantes (estáticos o no) se escriben en lowerCamelCase .

Estos nombres suelen ser sustantivos o frases nominales. Por ejemplo, computedValues o index .

5.2.6 Nombres de parámetros

Los nombres de los parámetros se escriben en lowerCamelCase .

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

5.2.7 Nombres de variables locales

Los nombres de las variables locales se escriben en lowerCamelCase .

Incluso cuando son finales e inmutables, las variables locales no se consideran constantes y no se las debe diseñar como tal.

5.2.8 Nombres de variables de tipo

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

Una sola letra mayúscula, seguida opcionalmente por un solo número (como E , T , X , T2 )
Un nombre en el formato utilizado para clases (ver Sección 5.2.2, Nombres de clases ), seguido de la letra mayúscula T (ejemplos: RequestT , FooBarT ).

5.3 Caso Camel: definición

A veces hay más de una forma razonable de convertir una frase en inglés a CamelCase, como cuando se utilizan acrónimos o construcciones inusuales como "IPv6" o "iOS". Para mejorar la previsibilidad, Google Style especifica el siguiente esquema (casi)
determinista.

Comenzando con la forma en prosa del nombre:

1. Convierta la frase a ASCII simple y elimine los apóstrofes. Por ejemplo, «algoritmo de Müller» podría convertirse en «algoritmo de Mueller».
2. Divida este resultado en palabras, dividiéndolo en espacios y cualquier puntuación restante (normalmente guiones).
Recomendado: si alguna palabra ya tiene la forma convencional de CamelCase en el uso común, sepárela en sus partes constituyentes (p. ej., "AdWords" se convierte en "adwords"). Tenga en cuenta que una palabra como "iOS" no está realmente
en CamelCase ; desafía cualquier convención, por lo que esta recomendación no aplica.
3. Ahora escriba todo en minúsculas (incluidas las siglas) y luego en mayúsculas solo el primer carácter de:
... cada palabra, para producir mayúsculas y minúsculas , o
... cada palabra excepto la primera, para obtener la letra camel case en minúscula
4. Finalmente, une todas las palabras en un único identificador. Ten en cuenta que el uso de mayúsculas y minúsculas en las palabras originales se ignora casi por completo.

En circunstancias muy raras (por ejemplo, números de versiones de varias partes), es posible que necesite utilizar guiones bajos para separar números adyacentes, ya que los números no tienen variantes en mayúsculas y minúsculas.

Ejemplos:

Forma en prosa Correcto Incorrecto

"Solicitud HTTP XML" XmlHttpRequest XMLHTTPRequest

"nuevo ID de cliente" newCustomerId newCustomerID

"cronómetro interno" innerStopwatch innerStopWatch

"¿Es compatible con IPv6 en iOS?" supportsIpv6OnIos supportsIPv6OnIOS

Importador de YouTube YouTubeImporter

YoutubeImporter *

"Activar la verificación en dos pasos" turnOn2sv turnOn2Sv

"Guayaba 33.4.6" guava33_4_6 guava3346

*Aceptable, pero no recomendado.

Nota: Algunas palabras tienen guiones ambiguos en el idioma inglés: por ejemplo, "nonempty" y "non-empty" son correctos, por lo que los nombres de los métodos checkNonempty y checkNonEmpty son igualmente correctos.

6 Prácticas de programación

6.1 @Override : siempre usado

Un método se marca con la @Override anotación siempre que sea válido. Esto incluye un método de clase que sobreescribe un método de superclase, un método de clase que implementa un método de interfaz, un método de interfaz que reespecifica un
método de superinterfaz y un método de acceso declarado explícitamente para un componente de registro.

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

6.2 Excepciones detectadas: no ignoradas

Rara vez es correcto no hacer nada ante una excepción detectada. (Las respuestas típicas son registrarla o, si se considera "imposible", volver a lanzarla como un AssertionError .)

Cuando realmente es apropiado no realizar ninguna acción en un bloque catch, la razón por la que esto está justificado se explica en un comentario.

try { int i = Integer . parseInt ( respuesta ); return handleNumericResponse ( i ); } catch ( NumberFormatException ok ) { // no es numérico; está bien, simplemente continúe } return handleTextResponse ( respu

6.3 Miembros estáticos: calificados usando la clase

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

Foo aFoo = ...; Foo . un método estático (); // bueno aFoo . un método estático (); // algo maloThatYieldsAFoo (). un método estático (); //muy mal

6.4 Finalizadores: no utilizados

No anular . El soporte de finalización está programado para su eliminación . [Link]

7 Javadoc

7.1 Formato

7.1.1 Forma general

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

/**
*Aquí se escriben varias líneas de texto Javadoc.
* envuelto normalmente...
*/ método int público ( String p1 ) { ... }

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

/** Un fragmento especialmente corto de Javadoc. */

El formato básico siempre es aceptable. El formato de una sola línea puede sustituirse cuando todo el bloque de Javadoc (incluidos los marcadores de comentarios) cabe en una sola línea. Tenga en cuenta que esto solo aplica cuando no hay etiquetas de
bloque como @param .

7.1.2 Párrafos

Una línea en blanco (es decir, una línea que contiene solo el asterisco inicial alineado ( * )) aparece entre párrafos y antes del grupo de etiquetas de bloque, si lo hay. Cada párrafo, excepto el primero, tiene la etiqueta <p> inmediatamente antes de la
primera palabra, sin espacio después. Las etiquetas HTML para otros elementos de bloque, como <ul> o <table> , no van precedidas de <p> .

7.1.3 Etiquetas de bloque

Cualquiera de las etiquetas de bloque estándar que se utilizan aparece 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 se sangran cuatro (o más) espacios desde la posición de la etiqueta @ .

7.2 El fragmento de resumen

Cada bloque de 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 clases y métodos.

Este es un fragmento: un sintagma nominal o verbal, no una oración completa. No empieza con A {@code Foo} is a... , ni This method returns... , ni forma una oración imperativa completa como Save the record. . Sin embargo, el fragmento
se escribe con mayúscula y puntuación como si fuera una oración completa.

Consejo: Un error común es escribir Javadoc simple con el formato /** @return the customer ID */ . Esto es incorrecto y debería cambiarse a /** Returns the customer ID. */ o /** {@return the customer ID} */ .

7.3 Dónde se utiliza Javadoc

Como mínimo , Javadoc está presente para cada clase, miembro o componente de registro visible , con algunas excepciones que se indican a continuación. Una clase de nivel superior es visible si es public ; un miembro es visible si es public o
protected y la clase que lo contiene es visible; y un componente de registro es visible si el registro que lo contiene es visible.

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

7.3.1 Excepción: miembros que se explican por sí mismos

Javadoc es opcional para miembros "simples y obvios" y componentes de registros, como un método, si realmente no hay nada más que valga la pena decir excepto "el foo". getFoo()

Importante: No es apropiado citar esta excepción para justificar la omisión de información relevante que un lector típico podría necesitar conocer. Por ejemplo, para un componente de registro llamado canonicalName , no omita su documentación (con el
argumento de que solo indicaría @param canonicalName the canonical name ) si un lector típico podría no tener idea de lo que significa el término "nombre canónico".

7.3.2 Excepción: anulaciones

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

7.3.4 Javadoc no requerido

Otras clases, miembros y componentes de registros tienen Javadoc según sea necesario o deseado .

Siempre que se use 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 /** ).

No es estrictamente necesario que Javadoc siga las reglas de formato de las Secciones 7.1.1, 7.1.2, 7.1.3 y 7.2, aunque, por supuesto, se recomienda.