Java Language
Código oficial de Oracle estándar

Introducción

Observaciones

Convenciones de nombres

Nombres de paquetes

• Los nombres de los paquetes deben estar en minúsculas sin guiones bajos u otros caracteres especiales.
• Los nombres de los paquetes comienzan con la parte de autoridad anulada de la dirección web de la empresa del desarrollador. Esta parte puede ser seguida por una subestructura de paquete dependiente de la estructura del proyecto / programa.
• No utilice la forma plural. Siga la convención de la API estándar que utiliza, por ejemplo, java.lang.annotation y no java.lang.annotations .
• Ejemplos: com.yourcompany.widget.button , com.yourcompany.core.api

Clase, Interfaz y Nombres Enum

• Los nombres de clase y enumeración deben ser nombres.
• Los nombres de las interfaces normalmente deben ser sustantivos o adjetivos que terminen con ... capaces.
• Use mayúsculas y minúsculas con la primera letra de cada palabra en mayúsculas (es decir, CamelCase ).
• Empareja la expresión regular ^[AZ][a-zA-Z0-9]*$ .
• Use palabras completas y evite usar abreviaturas a menos que la abreviatura se use más ampliamente que la forma larga.
• Formatee una abreviatura como una palabra si es parte de un nombre de clase más largo.
• Ejemplos: ArrayList , BigInteger , ArrayIndexOutOfBoundsException , Iterable .

Nombres de los métodos

Los nombres de los métodos suelen ser verbos u otras descripciones de acciones

• Deben coincidir con la expresión regular ^[az][a-zA-Z0-9]*$ .
• Use mayúsculas y minúsculas con la primera letra en minúsculas.
• Ejemplos: toString , hashCode

Variables

Los nombres de las variables deben estar en mayúsculas y minúsculas con la primera letra en minúscula

• Empareja la expresión regular ^[az][a-zA-Z0-9]*$
• Recomendación adicional: Variables
• Ejemplos: elements , currentIndex

Variables de tipo

Para casos simples donde hay pocas variables de tipo involucradas, use una sola letra mayúscula.

• Coincidir con la expresión regular ^[AZ][0-9]?$
• Si una letra es más descriptiva que otra (como K y V para claves y valores en mapas o R para un tipo de retorno de función) use eso, de lo contrario use T
• Para los casos complejos en los que las variables de una sola letra se vuelven confusas, use nombres más largos escritos con mayúsculas y use el guión bajo ( _ ) para separar las palabras.
• Ejemplos: T , V , SRC_VERTEX

Constantes

Las constantes (campos static final cuyo contenido es inmutable, por reglas de idioma o por convención) deben nombrarse con todas las letras mayúsculas y el subrayado ( _ ) para separar las palabras.

• Coincidir con la expresión regular ^[AZ][A-Z0-9]*(_[A-Z0-9]+)*$
• Ejemplos: BUFFER_SIZE , MAX_LEVEL

Otras directrices sobre nombramiento

• Evite ocultar / sombrear métodos, variables y variables de tipo en ámbitos externos.
• Deje que la verbosidad del nombre se correlacione con el tamaño del alcance. (Por ejemplo, use nombres descriptivos para campos de clases grandes y nombres breves para variables locales de corta duración).
• Al nombrar miembros públicos estáticos, deje que el identificador sea auto-descriptivo si cree que serán importados estáticamente.
• Más información: Sección de nombres (en la guía de estilo de Java oficial)

_{Fuente: Directrices de estilo de Java de Oracle}

Archivos fuente de Java

• Todas las líneas deben terminarse con un carácter de avance de línea (LF, valor ASCII 10) y no, por ejemplo, CR o CR + LF.

• Puede que no haya ningún espacio en blanco al final de una línea.

• El nombre de un archivo de origen debe ser igual al nombre de la clase que contiene, seguido de la extensión .java , incluso para los archivos que solo contienen una clase privada de paquete. Esto no se aplica a los archivos que no contienen ninguna declaración de clase, como package-info.java .

Caracteres especiales

• Aparte de LF, el único carácter de espacio en blanco permitido es el espacio (valor ASCII 32). Tenga en cuenta que esto implica que otros caracteres de espacios en blanco (en, por ejemplo, literales de cadenas y caracteres) deben escribirse en forma de escape.

• \' , \" , \\ , \t , \b , \r , \f , y \n deben preferirse a los octales correspondientes (por ejemplo, \047 ) o Unicode (por ejemplo, \u0027 ) caracteres escapados.

• En caso de que sea necesario ir en contra de las reglas anteriores por el bien de la prueba, la prueba debe generar la entrada requerida programáticamente.

Declaración del paquete

package com.example.my.package;

La declaración del paquete no debe incluirse en línea, independientemente de si excede la longitud máxima recomendada de una línea.

Declaraciones de importación

// First java/javax packages
import java.util.ArrayList;
import javax.tools.JavaCompiler;

// Then third party libraries
import com.fasterxml.jackson.annotation.JsonProperty;

// Then project imports
import com.example.my.package.ClassA;
import com.example.my.package.ClassB;

// Then static imports (in the same order as above)
import static java.util.stream.Collectors.toList;

• Las declaraciones de importación deben ser ordenadas ...

  • ... principalmente por importaciones no estáticas / estáticas con importaciones no estáticas primero.
  • ... secundariamente por origen de paquete según el siguiente orden
    • paquetes de java
    • paquetes javax
    • paquetes externos (ej. org.xml)
    • paquetes internos (ej. com.sun)
  • … Terciario por paquete e identificador de clase en orden lexicográfico

• Las declaraciones de importación no deben incluirse en línea, independientemente de si exceden la longitud máxima recomendada de una línea.

• No deben estar presentes las importaciones no utilizadas.

Importaciones de comodines

• En general, las importaciones de comodines no deben utilizarse.
• Cuando se importa una gran cantidad de clases estrechamente relacionadas (como la implementación de un visitante en un árbol con docenas de clases distintas de "nodos"), se puede usar una importación de comodines.
• En cualquier caso, no se debe utilizar más de una importación de comodines por archivo.

Estructura de clase

Orden de los miembros de la clase

Los miembros de la clase deben ordenarse de la siguiente manera:

1. Campos (en orden público, protegido y privado).
2. Constructores
3. Métodos de fábrica
4. Otros Métodos (en orden público, protegido y privado).

No es necesario ordenar campos y métodos principalmente por sus modificadores de acceso o identificador.

Aquí hay un ejemplo de este orden:

class Example {

    private int i;

    Example(int i) {
        this.i = i;
    }

    static Example getExample(int i) {
        return new Example(i);
    }

    @Override
    public String toString() {
        return "An example [" + i + "]";
    }

}

Agrupación de miembros de la clase.

• Los campos relacionados deben agruparse.
• Un tipo anidado puede ser declarado justo antes de su primer uso; De lo contrario se debe declarar antes de los campos.
• Los constructores y los métodos sobrecargados deben agruparse por funcionalidad y ordenarse con una aridad creciente. Esto implica que la delegación entre estas construcciones fluye hacia abajo en el código.
• Los constructores deben agruparse sin otros miembros entre ellos.
• Las variantes sobrecargadas de un método deben agruparse juntas sin otros miembros entre ellas.

Modificadores

class ExampleClass {
    // Access modifiers first (don't do for instance "static public")
    public static void main(String[] args) {
        System.out.println("Hello World");
    }
}

interface ExampleInterface {
    // Avoid 'public' and 'abstract' since they are implicit
    void sayHello();
}

• Los modificadores deben ir en el siguiente orden

  • Modificador de acceso ( public / private / protected )
  • abstract
  • static
  • final
  • transient
  • volatile
  • default
  • synchronized
  • native
  • strictfp

• Los modificadores no deben escribirse cuando están implícitos. Por ejemplo, los métodos de interfaz no deben declararse public ni abstract , y las enums e interfaces anidadas no deben declararse estáticas.

• Los parámetros del método y las variables locales no deben declararse final menos que mejore la legibilidad o documente una decisión de diseño real.

• Los campos deben declararse final menos que haya una razón convincente para hacerlos mutables.

Sangría

• El nivel de sangrado es de cuatro espacios .
• Solo se pueden usar caracteres de espacio para la sangría. No hay pestañas.
• Las líneas vacías no deben ser sangradas. (Esto está implícito en la regla de espacio en blanco final).
• case líneas del case deben estar sangradas con cuatro espacios, y las declaraciones dentro del caso deben estar sangradas con otros cuatro espacios.

switch (var) {
    case TWO:
        setChoice("two");
        break;
    case THREE:
        setChoice("three");
        break;
    default:
        throw new IllegalArgumentException();
}

Consulte las instrucciones de ajuste para obtener instrucciones sobre cómo sangrar líneas de continuación.

Envolver declaraciones

• El código fuente y los comentarios generalmente no deben exceder los 80 caracteres por línea y rara vez, si alguna vez, exceden los 100 caracteres por línea, incluida la sangría.

  El límite de caracteres se debe juzgar caso por caso. Lo que realmente importa es la "densidad" semántica y la legibilidad de la línea. Hacer líneas gratuitamente largas las hace difíciles de leer; de manera similar, hacer "intentos heroicos" para encajarlos en 80 columnas también puede hacer que sean difíciles de leer. La flexibilidad descrita aquí apunta a permitir a los desarrolladores evitar estos extremos, no maximizar el uso del monitor de bienes raíces.

• Las URL o los comandos de ejemplo no se deben envolver.

// Ok even though it might exceed max line width when indented.
Error e = isTypeParam
        ? Errors.InvalidRepeatableAnnotationNotApplicable(targetContainerType, on)
        : Errors.InvalidRepeatableAnnotationNotApplicableInContext(targetContainerType));

// Wrapping preferable
String pretty = Stream.of(args)
                      .map(Argument::prettyPrint)
                      .collectors(joining(", "));

// Too strict interpretation of max line width. Readability suffers.
Error e = isTypeParam
        ? Errors.InvalidRepeatableAnnotationNotApplicable(
                targetContainerType, on)
        : Errors.InvalidRepeatableAnnotationNotApplicableInContext(
                targetContainerType);

// Should be wrapped even though it fits within the character limit
String pretty = Stream.of(args).map(Argument::prettyPrint).collectors(joining(", "));

• Se prefiere envolver en un nivel sintáctico más alto que envolver en un nivel sintáctico más bajo.

• Debe haber como máximo 1 declaración por línea.

• Una línea de continuación debe estar sangrada de una de las siguientes cuatro formas

  • Variante 1 : Con 8 espacios adicionales relativos a la sangría de la línea anterior.
  • Variante 2 : con 8 espacios adicionales en relación con la columna inicial de la expresión envuelta.
  • Variante 3 : alineada con la expresión de hermano anterior (siempre que quede claro que es una línea de continuación)
  • Variante 4 : Alineado con la llamada al método anterior en una expresión encadenada.

Declaraciones del método de envoltura

int someMethod(String aString,
               List<Integer> aList,
               Map<String, String> aMap,
               int anInt,
               long aLong,
               Set<Number> aSet,
               double aDouble) {
    …
}

int someMethod(String aString, List<Integer> aList,
        Map<String, String> aMap, int anInt, long aLong,
        double aDouble, long aLong) {
    …
}

int someMethod(String aString,
               List<Map<Integer, StringBuffer>> aListOfMaps,
               Map<String, String> aMap)
        throws IllegalArgumentException {
    …
}

int someMethod(String aString, List<Integer> aList,
        Map<String, String> aMap, int anInt)
                throws IllegalArgumentException {
    …
}

• Las declaraciones de métodos se pueden formatear enumerando los argumentos verticalmente, o por una nueva línea y +8 espacios adicionales
• Si es necesario ajustar una cláusula de lanzamientos, coloque el salto de línea delante de la cláusula de lanzamientos y asegúrese de que se destaque de la lista de argumentos, ya sea sangrando +8 con relación a la declaración de la función, o +8 con respecto a la línea anterior.

Expresiones de envoltura

• Si una línea se acerca al límite máximo de caracteres, siempre considere dividirlo en múltiples declaraciones / expresiones en lugar de envolver la línea.
• Romper ante los operadores.
• Romper antes de la. En las llamadas de método encadenado.

popupMsg("Inbox notification: You have "
        + newMsgs + " new messages");

// Don't! Looks like two arguments
popupMsg("Inbox notification: You have " +
         newMsgs + " new messages");

Espacio en blanco

Espacio en blanco vertical

• Se debe usar una sola línea en blanco para separar ...

  • Declaración del paquete
  • Declaraciones de clase
  • Constructores
  • Métodos
  • Inicializadores estáticos
  • Inicializadores de instancia

• ... y puede ser usado para separar grupos lógicos de

  • declaraciones de importación
  • campos
  • declaraciones

• Múltiples líneas en blanco consecutivas solo deben usarse para separar grupos de miembros relacionados y no como el espaciado entre miembros estándar.

Espacio en blanco horizontal

• Se debe usar un solo espacio ...

  • Para separar palabras clave de corchetes y llaves de apertura o cierre vecinos
  • Antes y después de todos los operadores binarios y el operador, como símbolos como las flechas en las expresiones lambda y los dos puntos mejorados para los bucles (pero no antes de los dos puntos de una etiqueta)
  • Después de // eso comienza un comentario.
  • Después de comas, separa los argumentos y los puntos y comas separan las partes de un bucle for.
  • Tras el paréntesis de cierre de un reparto.

• En declaraciones de variables no se recomienda alinear tipos y variables.

Declaraciones Variables

• Una variable por declaración (y como máximo una declaración por línea)
• Los corchetes de las matrices deben estar en el tipo ( String[] args ) y no en la variable ( String args[] ).
• Declare una variable local justo antes de usarla por primera vez e inicialícela lo más cerca posible de la declaración.

Anotaciones

Las anotaciones de la declaración deben colocarse en una línea separada de la declaración que se está anotando.

@SuppressWarnings("unchecked")
public T[] toArray(T[] typeHolder) {
    ...
}

Sin embargo, pocas anotaciones o anotaciones cortas que anotan un método de una sola línea se pueden colocar en la misma línea que el método si mejora la legibilidad. Por ejemplo, uno puede escribir:

@Nullable String getName() { return name; }

Por cuestiones de coherencia y legibilidad, todas las anotaciones deben colocarse en la misma línea o cada anotación debe colocarse en una línea separada.

// Bad.
@Deprecated @SafeVarargs
@CustomAnnotation
public final Tuple<T> extend(T... elements) {
    ...
}

// Even worse.
@Deprecated @SafeVarargs
@CustomAnnotation public final Tuple<T> extend(T... elements) {
    ...
}

// Good.
@Deprecated
@SafeVarargs
@CustomAnnotation
public final Tuple<T> extend(T... elements) {
    ...
}

// Good.
@Deprecated @SafeVarargs @CustomAnnotation
public final Tuple<T> extend(T... elements) {
    ...
}

Expresiones lambda

Runnable r = () -> System.out.println("Hello World");

Supplier<String> c = () -> "Hello World";

// Collection::contains is a simple unary method and its behavior is
// clear from the context. A method reference is preferred here.
appendFilter(goodStrings::contains);

// A lambda expression is easier to understand than just tempMap::put in this case
trackTemperature((time, temp) -> tempMap.put(time, temp));

• Las lambdas de expresión se prefieren a las lambdas de bloque de una sola línea.
• Las referencias a los métodos generalmente deben preferirse a las expresiones lambda.
• Para referencias de métodos de instancia unida, o métodos con una aridad mayor que uno, una expresión lambda puede ser más fácil de entender y, por lo tanto, preferible. Especialmente si el comportamiento del método no está claro en el contexto.
• Los tipos de parámetros deben omitirse a menos que mejoren la legibilidad.
• Si una expresión lambda se extiende sobre más de unas pocas líneas, considere crear un método.

Paréntesis redundantes

return flag ? "yes" : "no";

String cmp = (flag1 != flag2) ? "not equal" : "equal";

// Don't do this
return (flag ? "yes" : "no");

• Se pueden usar paréntesis de agrupación redundantes (es decir, paréntesis que no afectan la evaluación) si mejoran la legibilidad.
• Los paréntesis de agrupación redundantes normalmente se deben omitir en expresiones más cortas que involucren operadores comunes, pero se deben incluir en expresiones más largas o que involucren operadores cuya prioridad y asociatividad no estén claras sin paréntesis. Las expresiones ternarias con condiciones no triviales pertenecen a esta última.
• La expresión completa que sigue a una palabra clave de return no debe estar entre paréntesis.

Literales

long l = 5432L;
int i = 0x123 + 0xABC;
byte b = 0b1010;
float f1 = 1 / 5432f;
float f2 = 0.123e4f;
double d1 = 1 / 5432d;  // or 1 / 5432.0
double d2 = 0x1.3p2;

• long literales long deben usar el sufijo de la letra L mayúscula.
• Los literales hexadecimales deben usar letras mayúsculas A - F
• Todos los demás prefijos numéricos, infijos y sufijos deben usar letras minúsculas.

Tirantes

class Example {
    void method(boolean error) {
        if (error) {
            Log.error("Error occurred!");
            System.out.println("Error!");
        } else { // Use braces since the other block uses braces.
            System.out.println("No error");
        }
    }
}

• Las llaves de apertura deben colocarse en el final de la línea actual en lugar de en una línea por sí sola.

• Debería haber una nueva línea delante de una abrazadera de cierre, a menos que el bloque esté vacío (vea las formas cortas a continuación)

• Los frenos se recomiendan incluso cuando el lenguaje los hace opcionales, como los cuerpos de bucle y de una sola línea.

  • Si un bloque abarca más de una línea (incluidos los comentarios) debe tener llaves.
  • Si uno de los bloques en una sentencia if / else tiene llaves, el otro bloque también debe hacerlo.
  • Si el bloque es el último en un bloque adjunto, debe tener llaves.

• La palabra clave else , catch y while en do…while bucles van en la misma línea que la llave de cierre del bloque anterior.

Formas cortas

enum Response { YES, NO, MAYBE }
public boolean isReference() { return true; }

Las recomendaciones anteriores están destinadas a mejorar la uniformidad (y por lo tanto aumentar la familiaridad / legibilidad). En algunos casos, las "formas cortas" que se desvían de las pautas anteriores son tan legibles y pueden usarse en su lugar. Estos casos incluyen, por ejemplo, declaraciones de enumeración simples y métodos triviales y expresiones lambda.