1 Introduzione

Questo documento costituisce la definizione completa degli standard di codifica di Google per il codice sorgente nel linguaggio di programmazione Java™. Un file sorgente Java è descritto come in stile inGoogle se e solo se aderisce alle regole qui contenute.

Come altre guide di stile di programmazione, i problemi trattati riguardano non solo i problemi estetici del normatting, ma anche altri tipi di convenzioni o standard di codifica. Tuttavia, questo documentfocuses soprattutto sulle regole dure-e-veloci che seguiamo universalmente, andavoids che danno il consiglio che non è chiaramente applicabile (se dall’essere umano o dallo strumento).

1.1 Note terminologiche

In questo documento, se non diversamente chiarito:

1. Il termine classe viene utilizzato in modo inclusivo per indicare una classe “ordinaria”, una classe enum, un’interfaccia o un tipo di annotazione (@interface).
2. Il termine membro (di una classe) viene utilizzato in modo inclusivo per indicare una classe, un campo, un metodo o un costruttore nidificati; cioè, tutti i contenuti di primo livello di una classe tranne inizializzatori e commenti.
3. Il termine commento si riferisce sempre ai commenti di implementazione. Non usiamo la frase “commenti di documentazione”, invece usando il termine comune ” Javadoc.”

Altre” note terminologiche ” appariranno occasionalmente in tutto il documento.

1.2 Note guida

Il codice di esempio in questo documento non è normativo. Cioè, mentre gli esempi sono in stile Google, potrebbero non illustrare l’unico modo elegante per rappresentare il codice. Le scelte di formattazione facoltative effettuate negli esempi non devono essere applicate come regole.

2 Nozioni di base sul file sorgente

2.1 Nome file

Il nome del file sorgente è costituito dal nome case-sensitive della classe di primo livello che contiene(di cui esiste esattamente uno), più l’estensione.java.

2.2 Codifica file: UTF-8

I file sorgente sono codificati in UTF-8.

2.3 Caratteri speciali

2.3.1 Caratteri di spazi bianchi

A parte la sequenza del terminatore di linea, lo spazio orizzontale ASCII (0x20) è l’unico carattere di spazi bianchi che appare ovunque in un file sorgente. Ciò implica che:

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 Caratteri non ASCII

Per i caratteri non ASCII rimanenti, viene utilizzato il carattere Unicode effettivo(ad esempio ∞) o l’escape Unicode equivalente(ad esempio \u221e). La scelta dipende solo dache rende il codice più facile da leggere e capire, anche se Unicode escapesoutside letterali stringa e commenti sono fortemente scoraggiati.

Suggerimento: nel caso di escape Unicode, e occasionalmente anche quando vengono utilizzati caratteri actualUnicode, un commento esplicativo può essere molto utile.

Esempi:

Esempio	Discussione
String unitAbbrev = "μs";	Migliore: perfettamente chiaro anche senza un commento.
String unitAbbrev = "\u03bcs"; // "μs"	Consentito, ma non c’è motivo di farlo.
String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"	Consentito, ma scomodo e soggetto a errori.
String unitAbbrev = "\u03bcs";	Povero: il lettore non ha idea di cosa sia.
return '\ufeff' + content; // byte order mark	Buono: utilizzare escape per caratteri non stampabili e commentare se necessario.

Suggerimento: non rendere il codice meno leggibile semplicemente per paura che alcuni programmi potrebbero non gestire correttamente i caratteri non ASCII. Se ciò dovesse accadere, quei programmi sono rotti e devono essere riparati.

3 Struttura del file sorgente

Esattamente una riga vuota separa ogni sezione presente.

3.1 Informazioni sulla licenza o sul copyright, se presenti

Se le informazioni sulla licenza o sul copyright appartengono a un file, appartengono qui.

3.2 Istruzione pacchetto

L’istruzione pacchetto non è a capo riga. Il limite di colonna (Sezione 4.4, Limite di colonna: 100) non si applica alle istruzioni del pacchetto.

3.3 Istruzioni di importazione

3.3.1 Nessuna importazione di caratteri jolly

Le importazioni di caratteri jolly, statiche o di altro tipo, non vengono utilizzate.

3.3.2 No line-wrapping

istruzioni di importazione non sono line-wrapped. Il limite di colonna (Sezione 4.4, Limite di colonna: 100) non si applica alle dichiarazioni di importazione.

3.3.3 Ordinamento e spaziatura

Le importazioni sono ordinate come segue:

1. Tutte le importazioni statiche in un unico blocco.
2. Tutte le importazioni non statiche in un unico blocco.

Se sono presenti importazioni statiche e non statiche, una singola riga vuota separa i due blocchi. Non ci sono altre righe vuote tra le istruzioni di importazione.

All’interno di ogni blocco i nomi importati appaiono in ordine ASCII. (Nota: questo non è lo stesso delle istruzioni di importazione in ordine ASCII, poiché ‘.”ordina prima”;”.)

3.3.4 Nessuna importazione statica per le classi

L’importazione statica non viene utilizzata per le classi nidificate statiche. Sono importati conimportazioni normali.

3.4 Dichiarazione di classe

3.4.1 Esattamente una dichiarazione di classe di primo livello

Ogni classe di primo livello risiede in un proprio file sorgente.

3.4.2 Ordinamento dei contenuti della classe

L’ordine che scegli per i membri e gli inizializzatori della tua classe può avere un grande effetto sulearnability. Tuttavia, non esiste un’unica ricetta corretta su come farlo; diverse classi possono ordinare i loro contenuti in modi diversi.

Ciò che è importante è che ogni classe usi un ordine logico, che il manutentore potrebbe spiegare se richiesto. Ad esempio, i nuovi metodi non vengono aggiunti abitualmente alla fine della classe, in quanto ciò produrrebbe un ordinamento “cronologico per data aggiunta”, che non è un ordine logico.

3.4.2.1 Sovraccarichi: non dividere mai

Quando una classe ha più costruttori o più metodi con lo stesso nome, questi appaiono in modo sequenziale, senza altro codice in mezzo (nemmeno membri privati).

4 Formattazione

Terminologia Nota: il costrutto a blocchi si riferisce al corpo di una classe, metodo o costruttore. Si noti che, nella Sezione 4.8.3.1 inizializzatori onarray, qualsiasi inizializzatore di array può essere opzionalmente trattato come se fosse un costrutto simile a un blocco.

4.1 Parentesi graffe

4.1.1 le parentesi Graffe vengono utilizzati dove opzionale

le parentesi Graffe vengono utilizzati conifelsefordo ewhile dichiarazioni, anche quando il corpo è vuoto o contiene una sola istruzione.

4.1.2 Blocchi non vuoti: K& Stile R

Le parentesi seguono lo stile Kernighan e Ritchie(“Parentesi egiziane”)per blocchi non vuoti e costrutti simili a blocchi:

• Nessuna interruzione di riga prima della parentesi di apertura.
• Interruzione di riga dopo la parentesi graffa di apertura.
• Interruzione di riga prima della parentesi graffa di chiusura.
• Interruzione di riga dopo la parentesi graffa di chiusura, solo se tale parentesi termina un’istruzione o termina il corpo di un metodo, costruttore o classe denominata. Ad esempio, non vi è alcuna interruzione di riga dopo la parentesi se è seguita da else o da una virgola.

Esempi:

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

Alcune eccezioni per le classi enum sono riportate nella Sezione 4.8.1,Enum classes.

4.1.3 Blocchi vuoti: può essere conciso

Un blocco vuoto o un costrutto simile a un blocco può essere in stile K& R (come descritto in sezione 4.1.2). In alternativa, può essere chiuso immediatelyafter viene aperto, senza caratteri o interruzione di riga in mezzo({}), a meno che non sia parte dell’istruzione amulti-block (uno che contiene direttamente più blocchi:if/else otry/catch/finally).

Esempi:

 // 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 Rientro blocco: + 2 spazi

Ogni volta che viene aperto un nuovo blocco o costrutto simile a un blocco, il rientro aumenta di duespazi. Quando il blocco termina, il rientro ritorna al livello di rientro precedente. Il livello di rientro si applica sia al codice che ai commenti in tutto il blocco. (Vedere l’esempio nella Sezione 4.1.2,Blocchi non vuoti: K& Stile R.)

4.3 Un’istruzione per riga

Ogni istruzione è seguita da un’interruzione di riga.

4.4 Limite di colonna: 100

Il codice Java ha un limite di colonna di 100 caratteri. Un “carattere” indica qualsiasi punto di codice Unicode.Ad eccezione di quanto indicato di seguito, qualsiasi linea che superi questo limite deve essere avvolta dalla linea, come spiegato in Sezione 4.5, Avvolgimento della linea.

Ogni punto di codice Unicode conta come un carattere, anche se la sua larghezza di visualizzazione è maggiore o minore. Ad esempio,se si utilizzano caratteri fullwidth, è possibile scegliere di avvolgere la riga prima di quanto richiesto da questa regola.

Eccezioni:

1. Righe in cui non è possibile rispettare il limite di colonna (ad esempio, un URL lungo in Javadoc o un riferimento al metodo JSNI lungo).
2. package eimport istruzioni (vedere Sezioni 3.2 Istruzione pacchetto e 3.3 istruzioni Importazione).
3. Righe di comando in un commento che può essere tagliato e incollato in una shell.

4.5 Line-wrapping

Terminologia Nota: quando il codice che potrebbe altrimenti occupare legalmente una singola riga è diviso in più righe, questa attività viene chiamata line-wrapping.

Non esiste una formula completa e deterministica che mostri esattamente come eseguire il line-wrap in ogni situazione. Molto spesso ci sono diversi modi validi per avvolgere la stessa parte di codice.

Nota: mentre il motivo tipico per il line-wrapping è quello di evitare il overflow del limite di colonna, anche il codice che di fatto rientrerebbe nel limite di colonna potrebbe essere avvolto a discrezione dell’autore.

Suggerimento: l’estrazione di un metodo o di una variabile locale può risolvere il problemasenza la necessità di eseguire il line-wrap.

4.5.1 Dove rompere

La prima direttiva del line-wrapping è: preferisco rompere a un livello sintattico più alto. Inoltre:

1. Quando una linea viene interrotta da un operatore non assegnatario, l’interruzione viene prima del simbolo. (Si noti che questa non è la stessa pratica utilizzata in Google style per altri linguaggi, come C++ e JavaScript.)
   • Questo vale anche per i seguenti di operatore “-come” simboli:
     • il punto separatore (.)
     • i due punti di un metodo di riferimento (::)
     • una e commerciale in un tipo di limite (<T extends Foo & Bar>)
     • un tubo in un blocco catch (catch (FooException | BarException e)).
2. Quando una linea viene interrotta da un operatore di assegnazione, l’interruzione viene in genere dopo il simbolo, ma in entrambi i casi è accettabile.
   • Questo vale anche per i due punti “assignment-operator-like” in un’istruzione avanzatafor (“foreach”).
3. Un nome di metodo o costruttore rimane collegato alla parentesi aperta (() che lo segue.
4. Una virgola (,) rimane collegata al token che lo precede.
5. Una linea non viene mai interrotta adiacente alla freccia in un lambda, tranne che un’interruzione può venire immediatamente dopo la freccia se il corpo del lambda è costituito da una singola espressione non rotta. Esempi:

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

Nota: L’obiettivo principale per il line wrapping è avere clearcode, non necessariamente codice che si adatta al minor numero di righe.

4.5.2 Rientro linee di continuazione almeno +4 spazi

Quando line-wrapping, ogni linea dopo la prima (ogni linea di continuazione) è indentedat almeno +4 dalla linea originale.

Quando ci sono più linee di continuazione, il rientro può essere variato oltre +4 asdesired. In generale, due linee di continuazione usano lo stesso livello di indentazione se e solo se loroiniziare con elementi sintatticamente paralleli.

Sezione 4.6.3 sugli indirizzi di allineamento orizzontalela pratica scoraggiata di utilizzare un numero variabile di spazi per allineare determinati token con linee precedenti.

4.6 Spazi bianchi

4.6.1 Spazi bianchi verticali

Appare sempre una singola riga vuota:

1. Tra membri consecutivi o inizializzatori di una classe: campi, costruttori, metodi, classi nidificate, inizializzatori statici e inizializzatori di istanze.
   • Eccezione: una riga vuota tra due campi consecutivi (senza altro codice tra di loro) è facoltativa. Tali righe vuote vengono utilizzate se necessario per creare raggruppamenti logici di campi.
   • Eccezione: le righe vuote tra le costanti enum sono trattate nella Sezione 4.8.1.
2. Come richiesto da altre sezioni di questo documento (ad esempio Sezione 3, Struttura del file sorgente e Sezione 3.3, istruzioni di importazione).

Una singola riga vuota può anche apparire ovunque migliora la leggibilità, ad esempio tra le dichiarazioni per organizzare il codice in sottosezioni logiche. Una riga vuota prima del primo membro orinitializer, o dopo l’ultimo membro o inizializzatore della classe, non è né incoraggiata nordiscouraged.

Sono consentite più righe vuote consecutive, ma mai richieste (o incoraggiate).

4.6.2 Spazi bianchi orizzontali

Oltre a dove richiesto dalla lingua o da altre regole di stile, e oltre a letterali, commenti ejavadoc, un singolo spazio ASCII appare solo nei seguenti punti.

1. Separare ogni parola riservata, come iffor o catch, da una parentesi aperta (() che segue in quella riga
2. Separare ogni parola riservata, ad esempio else o catch, da una parentesi graffa di chiusura (}) che lo precede sulla linea
3. Prima di ogni aperta parentesi graffa ({), con due eccezioni:
   • @SomeAnnotation({a, b}) (non viene utilizzato spazio)
   • String x = {{"foo"}}; (non è richiesto spazio tra{{, dal punto 8 sotto)
4. Su entrambi i lati di qualsiasi operatore binario o ternario. Questo vale anche per i seguenti simboli “operator-like”:
   • la e commerciale in un tipo congiuntivo legato: <T extends Foo & Bar>
   • la pipe per un blocco catch che gestisce più eccezioni: catch (FooException | BarException e)
   • i due punti (:) in un’istruzione avanzata for (“foreach”)
   • la freccia in un’espressione lambda: (String str) -> str.length()

   ma non

   • i due punti (::) di un metodo di riferimento, che viene scritto come Object::toString
   • il punto separatore (.), che è scritto come object.toString()
5. Dopo ,:; o la parentesi di chiusura ()) di un cast
6. Su entrambi i lati del doppio slash (//) che inizia un fine riga di commento. Qui, più spazi sono consentiti, ma non richiesti.
7. Tra il tipo e la variabile di una dichiarazione: List<String> list
8. Opzionale solo all’interno di parentesi graffe di un vettore di inizializzazione
   • new int {5, 6} e new int { 5, 6 } sono entrambi validi
9. Tra un tipo di annotazione e o ....

Questa regola non viene mai interpretata come che richiede o vieta lo spazio aggiuntivo all’inizio o al trend di una linea; riguarda solo lo spazio interno.

4.6.3 Allineamento orizzontale: mai richiesto

Nota terminologica: L’allineamento orizzontale è la pratica di aggiungere un numero variabile di spazi aggiuntivi nel codice con l’obiettivo di far apparire determinati token direttamente sotto determinati altri token sulle righe precedenti.

Questa pratica è consentita, ma non è mai richiesta da Google Style. Non è nemmeno necessario mantenere l’allineamento orizzontale in luoghi in cui è già stato utilizzato.

Ecco un esempio senza allineamento, quindi usando l’allineamento:

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

Suggerimento: l’allineamento può aiutare la leggibilità, ma crea problemi per la manutenzione futura. Considera un cambiamento futuro che deve toccare solo una riga. Questa modifica può lasciare la formattazione precedentemente piacevole storpiata, e questo è permesso. Più spessoesso richiede al codificatore (forse tu) di regolare lo spazio bianco anche sulle linee vicine, possibilmentetriggering una serie a cascata di riformattazioni. Quel cambiamento di una riga ora ha un ” raggio di esplosione.”Questo può nel peggiore dei casi portare a un lavoro inutile, ma nel migliore dei casi corrompe ancora la cronologia delle versioni, rallenta i revisori e aggrava i conflitti di fusione.

4.7 Raggruppamento delle parentesi: consigliato

Le parentesi di raggruppamento opzionali vengono omesse solo quando l’autore e il revisore concordano sul fatto che non vi è alcuna possibilità ragionevole che il codice venga interpretato male senza di loro, né avrebbero reso il codeeasier da leggere. Non è ragionevole supporre che ogni lettore abbia memorizzato l’intera tabella di precedenza Javaoperator.

4.8 Costrutti specifici

4.8.1 Classi Enum

Dopo ogni virgola che segue una costante enum, un’interruzione di riga è facoltativa. Sono consentite anche blankline aggiuntive (di solito solo una). Questa è una possibilità:

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

Una classe enum senza metodi e senza documentazione sulle sue costanti può facoltativamente essere formattata come se fosse un inizializzatore di array (vedere Sezione 4.8.3.1 onarray initializers).

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

Poiché le classi enum sono classi, si applicano tutte le altre regole per la formattazione delle classi.

4.8.2 Dichiarazioni di variabili

4.8.2.1 Una variabile per dichiarazione

Ogni dichiarazione di variabile (campo o locale) dichiara una sola variabile: dichiarazioni comeint a, b; non vengono utilizzate.

Eccezione: Più dichiarazioni di variabili sono accettabili nell’intestazione di un ciclofor.

4.8.2.2 Dichiarato quando necessario

Le variabili locali non vengono abitualmente dichiarate all’inizio del loro costrutto containingblock o block-like. Invece, le variabili locali vengono dichiarate vicine al punto in cui vengono utilizzate per la prima volta (entro limiti ragionevoli), per ridurre al minimo il loro ambito. Le dichiarazioni di variabili locali in genere hannoinitializers o vengono inizializzate immediatamente dopo la dichiarazione.

4.8.3 Array

4.8.3.1 Inizializzatori di array: può essere “block-like”

Qualsiasi inizializzatore di array può opzionalmente essere formattato come se fosse un “block-likeconstruct.”Per esempio, i seguenti sono tutti validi (non 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 N. C-style dichiarazioni di matrice

Le parentesi quadre fanno parte del tipo, non la variabile:String args nonString args.

4.8.4 Istruzioni switch

Terminologia Nota: All’interno delle parentesi del blocco aswitch sono presenti uno o più gruppi di istruzioni. Ogni gruppo di istruzioni è costituito da una o più etichette di commutazione (case FOO: odefault:), seguite da una o più istruzioni (o, per l’ultimo gruppo di istruzioni, zero o più istruzioni).

4.8.4.1 Rientro

Come con qualsiasi altro blocco, il contenuto di un blocco switch è rientrato +2.

Dopo un’etichetta di commutazione, c’è un’interruzione di riga e il livello di rientro viene aumentato +2, esattamente come se si aprisse un blocco. La seguente etichetta di commutazione ritorna al precedente indentationlevel, come se un blocco fosse stato chiuso.

4.8.4.2 Fall-through: commentato

all’Interno di un interruttore di blocco, ogni istruzione di gruppo chiude bruscamente (con unbreakcontinuereturn o eccezione generata), o è contrassegnato con un commentto indicare che l’esecuzione o potrebbe continuare la successiva istruzione di gruppo. Anycomment che comunica l’idea di fall-through è sufficiente (in genere// fall through). Questo commento speciale non è richiesto inl’ultimo gruppo di istruzioni del blocco switch. Esempio:

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

Si noti che non è necessario alcun commento dopo case 1:, solo alla fine del gruppo di istruzioni.

4.8.4.3 Il caso default è presente

Ogni istruzione switch include un default statementgroup, anche se non contiene alcun codice.

Eccezione: un’istruzione switch per un tipoenum può omettere il gruppo di istruzionidefault, se include casi espliciti che coprono tutti i possibili valori di quel tipo. Ciò consente agli IDE o ad altri strumenti di staticanalysis di emettere un avviso in caso di casi mancati.

4.8.5 Annotazioni

Le annotazioni che si applicano a una classe, un metodo o un costruttore appaiono immediatamente dopo il blocco di documentazione e ogni annotazione è elencata su una riga a sé stante (ovvero, una riga di annotazione). Queste interruzioni di riga non costituiscono il line-wrapping (Section4.5, Line-wrapping), quindi il livello di indentazione non è aumentato. Esempio:

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

Eccezione: Un singolo senza parametri annotationmay invece appaiono insieme con la prima riga della firma, per esempio:

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

Annotazioni applicazione di un campo anche apparire immediatamente dopo il blocco di documentazione, ma in tal caso, più annotazioni (possibilmente con parametri) possono essere elencati sulla stessa linea;per esempio:

@Partial @Mock DataLoader loader;

non Ci sono regole specifiche per la formattazione delle annotazioni sui parametri, variabili locali, o tipi.

Questa sezione affronta i commenti di implementazione. Javadoc è indirizzato separatamente inSezione 7, Javadoc.

Qualsiasi interruzione di riga può essere preceduta da spazi bianchi arbitrari seguiti da un commento di implementazione.Tale commento rende la riga non vuota.

4.8.6.1 Stile di commento del blocco

I commenti dei blocchi sono rientrati allo stesso livello del codice circostante. Possono essere in stile/* ... */ o// .... Per i commenti a più righe/* ... */, le righe successive devono iniziare con* allineato con * sulla riga precedente.

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

I commenti non sono racchiusi in caselle disegnate con asterischi o altri caratteri.

Suggerimento: quando si scrivono commenti su più righe, utilizzare lo stile/* ... */ se si desidera che i formattatori automatici di codice strappino le righe quando necessario (stile paragrafo). La maggior parte dei formattatori non riavvolge le linee nei blocchi di commento di stile// ....

4.8.7 Modificatori

Modificatori di classe e membro, quando presenti, appaiono nell’orderrecommended dalla specifica del linguaggio Java:

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

4.8.8 Letterali numerici

long-valued integer literals usa un suffisso maiuscoloL, neverlowercase (per evitare confusione con la cifra1). Ad esempio, 3000000000Lanziché 3000000000l.

5 Denominazione

5.1 Regole comuni a tutti gli identificatori

Gli identificatori utilizzano solo lettere e cifre ASCII e, in un piccolo numero di casi indicati di seguito, caratteri di sottolineatura. Così ogni nome identificatore valido è abbinato dall’espressione regolare\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.

I nomi delle classi sono in genere nomi o frasi sostantivi. Ad esempio,Character oImmutableList. I nomi delle interfacce possono anche essere nomi o frasi (ad esempio,List), ma a volte possono essere aggettivi o frasi aggettivi (ad esempio,Readable).

Non esistono regole specifiche o convenzioni ben consolidate per la denominazione dei tipi di annotazione.

Le classi di test sono denominate a partire dal nome della classe che stanno testando e terminano conTest. Ad esempio,HashTest oHashIntegrationTest.

5.2.3 Nomi dei metodi

I nomi dei metodi sono scritti in minuscolo.

I nomi dei metodi sono in genere verbi o frasi verbali. Ad esempio,sendMessage ostop.

I caratteri di sottolineatura possono apparire nei nomi dei metodi di test JUnit per separare i componenti logici di thename, con ogni componente scritto in minuscolo.Un modello tipico è <methodUnderTest>_<state>, ad esempio pop_emptyStack. Non c’è nessuno correttomodo per nominare i metodi di prova.

5.2.4 Nomi costanti

I nomi costanti utilizzanoCONSTANT_CASE: tutte le lettere maiuscole, con ogni parola separata dalla successiva da un singolo trattino basso. Ma che cosa è aconstant, esattamente?

Le costanti sono campi finali statici i cui contenuti sono profondamente immutabili e i cui metodi hanno effetti collaterali non rilevabili. Ciò include primitive, stringhe, tipi immutabili e immutablecollections di tipi immutabili. Se uno qualsiasi dello stato osservabile dell’istanza può cambiare, non è aconstant. La semplice intenzione di non mutare mai l’oggetto non è sufficiente. Esempio:

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

Questi nomi sono tipicamente nomi o frasi sostantivi.

5.2.5 Nomi di campo non costanti

I nomi di campo non costanti (statici o di altro tipo) vengono scritti in minuscolo.

Questi nomi sono in genere nomi o frasi sostantivi. Ad esempio,computedValues oindex.

5.2.6 Nomi dei parametri

I nomi dei parametri sono scritti in minuscolo.

I nomi dei parametri di un carattere nei metodi pubblici dovrebbero essere evitati.

5.2.7 Nomi di variabili locali

I nomi di variabili locali sono scritti in minuscolo.

Anche quando definitive e immutabili, le variabili locali non sono considerate costanti e non dovrebbero essere stilizzate come costanti.

5.2.8 Tipo i nomi delle variabili

Ogni tipo di variabile è denominato in una delle due stili:

• Una singola lettera maiuscola, eventualmente seguito da un singolo numero (ad esempio ETXT2)
• Un nome nel modulo utilizzato per le lezioni (vedere la Sezione 5.2.2, i nomi di Classe), seguito da una lettera maiuscola T (esempi: RequestTFooBarT).

5.3 Caso Camel: definito

A volte c’è più di un modo ragionevole per convertire una frase inglese in caso camel,ad esempio quando sono presenti acronimi o costrutti insoliti come “IPv6” o “iOS”. Per migliorarepredictability, Google Style specifica il seguente schema (quasi) deterministico.

Iniziando con la forma in prosa del nome:

1. Converti la frase in semplice ASCII e rimuovi eventuali apostrofi. Ad esempio,” algoritmo di Müller “potrebbe diventare”algoritmo di Muellers”.
2. Dividi questo risultato in parole, suddividendo gli spazi e qualsiasi punteggiatura rimanente (in genere trattini).
   • Consigliato: se una parola ha già un aspetto convenzionale del cammello nell’uso comune, dividi questa nelle sue parti costitutive (ad esempio, “AdWords” diventa “ad words”). Si noti che una parola come “iOS” non è realmente nel caso camel di per sé; sfida qualsiasi convenzione, quindi questa raccomandazione non si applica.
3. Ora tutto in minuscolo (compresi gli acronimi), quindi in maiuscolo solo il primo carattere di:
   • … ogni parola, per produrre il caso superiore del cammello, o
   • … ogni parola tranne la prima, per produrre caso cammello inferiore
4. Infine, unire tutte le parole in un unico identificatore.

Si noti che l’involucro delle parole originali è quasi completamente ignorato. Esempio:

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: sempre usato

Un metodo è contrassegnato con l’annotazione@Override quando è legale. Questo include un metodo di classe che sostituisce un metodo superclasse, un metodo di classe che implementa un metodo di interfaccia e un metodo di interfaccia che rispetta un metodo di superinterfacemethod.

Eccezione:@Overridepuò essere omessa quando il metodo padre è @Deprecated.

6.2 Eccezioni catturate: non ignorate

Tranne come indicato di seguito, è molto raramente corretto non fare nulla in risposta a una caughtexception. (Le risposte tipiche sono registrarlo, o se è considerato “impossibile”, ridurlo comeAssertionError.)

Quando è veramente appropriato non intraprendere alcuna azione in un blocco catch, il motivo per cui questo è giustificato è spiegato in un commento.

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

Eccezione: nei test, un’eccezione rilevata può essere ignorata senza commento se il suo nome è o inizia con expected. Thefollowing è un idioma molto comune per garantire che il codice in prova lanci un’eccezione del tipo previsto, quindi un commento non è necessario qui.

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

6.3 Membri statici: qualificati usando la classe

Quando un riferimento a un membro della classe statica deve essere qualificato, è qualificato con il nome di quella classe, non con un riferimento o un’espressione del tipo di quella classe.

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

6.4 Finalizzatori: non utilizzati

È estremamente raro sovrascrivere Object.finalize.

Suggerimento: non farlo. Se è assolutamente necessario, prima leggere e comprendere l’efficace elemento Java 7, “Evitare i finalizzatori”, con molta attenzione, e quindi non farlo.

7 Javadoc

7.1 Formattazione

7.1.1 Modulo generale

La formattazione di base dei blocchi Javadoc è come si vede in questo esempio:

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

… oppure in questo esempio a riga singola:

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

La forma di base è sempre accettabile. Il modulo a riga singola può essere sostituito quando l’intero blocco Javadoc (inclusi i marcatori di commento) può adattarsi a una singola riga. Si noti che questo si applica solo quando non ci sono tag di blocco come @return.

7.1.2 Paragrafi

Una riga vuota, ovvero una riga contenente solo l’asterisco iniziale allineato (*), appare tra i paragrafi e prima del gruppo di tag di blocco ifpresent. Ogni paragrafo ma il primo ha<p> immediatamente prima della prima parola, senza spazio dopo.

7.1.3 Tag di blocco

Qualsiasi “tag di blocco” standard utilizzato appare nell’ordine@param@return@throws@deprecated, e questi quattro tipi neverappear con una descrizione vuota. Quando un tag di blocco non si adatta a una singola riga, le linee di continuazionesono rientrate di quattro (o più) spazi dalla posizione di @.

7.2 Il frammento di riepilogo

Ogni blocco Javadoc inizia con un breve frammento di riepilogo. Thisfragment è molto importante: è l’unica parte del testo che appare in determinati contesti come indici di classe e metodo.

Questo è un frammento—una frase sostantiva o una frase verbale, non una frase completa. Non inizia con A {@code Foo} is a..., oThis method returns..., né forma una frase imperativa completa comeSave the record.. Tuttavia, il frammento è in maiuscolo epuntuato come se fosse una frase completa.

Suggerimento: Un errore comune è quello di scrivere semplice Javadoc nella forma /** @return the customer ID */. Questo non è corretto e dovrebbe essere modificato in /** Returns the customer ID. */.

7.3 Dove Javadoc è usato

Al minimo, Javadoc è presente per ognipublic classe, e ognipublic oprotected membro di tale classe, con alcune eccezioninotato di seguito.

Possono essere presenti anche contenuti Javadoc aggiuntivi, come spiegato nella Sezione 7.3.4,Javadoc non richiesto.

7.3.1 Eccezione: metodi autoesplicativi

Javadoc è facoltativo per metodi “semplici, ovvi” comegetFoo, nei casi in cui non c’è davvero e veramente nient’altro che valga la pena di dire ma “Restituisce il foo”.

Importante: non è opportuno citare questa eccezione per giustificare l’invio di informazioni pertinenti che un lettore tipico potrebbe dover conoscere. Ad esempio, per un methodnamedgetCanonicalName, non omettere la sua documentazione(con la logica che direbbe solo/** Returns the canonical name. */) se un lettore tipico potrebbe non avere ideache significa il termine “nome canonico”!

7.3.2 Eccezione: sovrascrive

Javadoc non è sempre presente su un metodo che sovrascrive un metodo supertype.

7.3.4 Javadoc non richiesto

Altre classi e membri hanno Javadoc come necessario o desiderato.