1 Inleiding

Dit document dient als de volledige definitie van Google ‘ s coderingsstandaarden voor broncode in de programmeertaal Java™. Een Java bronbestand wordt beschreven als inGoogle stijl dan en alleen als het voldoet aan de regels hierin.

net als andere programmeerstijlgidsen omvatten de behandelde onderwerpen niet alleen esthetische kwesties op het gebied van formatteren, maar ook andere soorten conventies of coderingsstandaarden. Echter, dit document richt zich voornamelijk op de harde-en-snelle regels die we universeel volgen, en avoids het geven van advies dat niet duidelijk afdwingbaar is (of door mens of gereedschap).

1.1 terminologie opmerkingen

in dit document, tenzij anders verduidelijkt:

1. De term klasse wordt insluitend gebruikt om een “gewone” klasse, enum-klasse, interface of annotatietype te betekenen (@interface).
2. de term lid (van een klasse) wordt inclusief gebruikt om een geneste klasse, veld, Methode of constructor te betekenen; dat wil zeggen, alle top-level inhoud van een klasse behalve initializers en opmerkingen.
3. de term commentaar verwijst altijd naar implementatiecommentaren. We gebruiken niet de uitdrukking “documentatie opmerkingen”, in plaats daarvan gebruiken we de algemene term “Javadoc.”

andere” terminologienummers ” komen soms in het hele document voor.

1.2 aanwijzingen

voorbeeldcode in dit document is niet-normatief. Dat wil zeggen, terwijl de voorbeeldenzijn in Google-stijl, ze kunnen niet illustreren de enige stijlvolle manier om de code te vertegenwoordigen. Optionele opmaakkeuzes in voorbeelden moeten niet als regels worden afgedwongen.

2 basis van bronbestand

2.1 bestandsnaam

De naam van het bronbestand bestaat uit de hoofdlettergevoelige naam van de hoogste klasse die het bevat(waarvan er precies één is), plus de.java extensie.

2.2 bestandscodering: UTF-8

bronbestanden worden gecodeerd in UTF-8.

2.3 speciale tekens

2.3.1 Witruimtekarakters

afgezien van de regelafsluiterreeks, is de ASCII horizontale spacecharacter (0x20) het enige witruimtekarakter dat overal in een bronbestand voorkomt. Dit houdt in dat:

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 niet-ASCII-tekens

voor de overige Niet-ASCII-tekens wordt ofwel het werkelijke Unicode-teken(bijv. ∞) ofwel de equivalente Unicode-escape (bijv. \u221e) gebruikt. De keuze hangt alleen af vandie maakt de code gemakkelijker te lezen en te begrijpen, hoewel Unicode escapes Outside string literals en commentaren worden sterk ontmoedigd.

Tip: in het geval van Unicode escape, en soms zelfs wanneer actualUnicode-tekens worden gebruikt, kan een verklarende opmerking zeer nuttig zijn.

voorbeelden:

	voorbeeld	discussie
String unitAbbrev = "μs";	Best: volkomen duidelijk, zelfs zonder commentaar.
String unitAbbrev = "\u03bcs"; // "μs"	toegestaan, maar er is geen reden om dit te doen.
String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"	toegestaan, maar onhandig en vatbaar voor fouten.
String unitAbbrev = "\u03bcs";	Slecht: de lezer heeft geen idee wat dit is.
return '\ufeff' + content; // byte order mark	goed: gebruik escapes voor niet-afdrukbare tekens, en commentaar indien nodig.

Tip: maak uw code nooit minder leesbaar uit angst dat sommige programma ‘ s niet-ASCII-tekens niet goed kunnen verwerken. Als dat gebeurt, zijn die programma ‘ s kapot en moeten ze worden gerepareerd.

3 bronbestandstructuur

exact één lege regel scheidt elke sectie die aanwezig is.

3.1 licentie-of copyrightinformatie, indien aanwezig

indien licentie-of copyrightinformatie in een bestand thuishoort, hoort deze hier.

3.2 Package statement

het package statement is niet met de regel omwikkeld. De kolomlimiet (paragraaf 4.4,Kolomlimiet: 100) is niet van toepassing op pakketverklaringen.

3.3 invoerverklaringen

3.3.1 geen invoer met wildcard

invoer met Wildcard, statisch of anderszins, wordt niet gebruikt.

3.3.2 geen regelafbreking

Importafschriften zijn niet regelafbrekend. De kolomlimiet (punt 4.4,Kolomlimiet: 100) is niet van toepassing op invoerstaten.

3.3.3 volgorde en spatiëring

invoer wordt als volgt geordend:

1. alle statische invoer in één blok.
2. alle niet-statische invoer in één blok.

als er zowel statische als niet-statische invoer is, scheidt één enkele lege regel de twee blokken. Er zijn geen andere lege regels tussen importafschriften.

binnen elk blok verschijnen de geïmporteerde namen in ASCII sorteervolgorde. (Opmerking: Dit is niet hetzelfde als de import verklaringen in ASCII sorteervolgorde, sinds ‘.’sorteert voor’;’.)

3.3.4 geen statische import voor klassen

statische import wordt niet gebruikt voor statische geneste klassen. Zij worden met normale invoer ingevoerd.

3.4 Klasse declaratie

3.4.1 precies één Topklasse declaratie

elke Topklasse bevindt zich in een eigen bronbestand.

3.4.2 volgorde van klasseninhoud

De volgorde die u kiest voor de leden en initializers van uw klasse kan een groot effect hebben op de leesbaarheid. Er is echter geen enkel correct recept voor hoe het te doen; verschillende klassen kunnen hun inhoud op verschillende manieren ordenen.

wat belangrijk is, is dat elke klasse een logische volgorde gebruikt, die de beheerder desgevraagd zou kunnen uitleggen. Bijvoorbeeld, nieuwe methoden worden niet gewoon gewoonlijk toegevoegd aan het einde van de klasse, omdat dat zou opleveren “chronologisch op Datum toegevoegd” volgorde, die geen logical volgorde.

3.4.2.1 overbelasting: splits

nooit wanneer een klasse meerdere constructors heeft, of meerdere methoden met dezelfde naam, verschijnen deze achtereenvolgens, met geen andere code ertussen (zelfs geen privé-leden).

4 opmaak

terminologie opmerking: blokachtige constructie verwijst naar het lichaam van een klasse, methode of constructor. Merk op dat, door paragraaf 4.8.3.1 onarray initializers, elke array initializermay optioneel worden behandeld alsof het een blok-achtige constructie.

4.1 accolades

4.1.1 accolades worden gebruikt wanneer optionele

accolades worden gebruikt metifelsefordo enwhile thebody is leeg of bevat slechts een enkele statement.

4.1.2 niet-lege blokken: K & r stijl

accolades volgen de Kernighan-en Ritchie-stijl (“Egyptische accolades”) voor niet-lege blokken en blokachtige constructies:

• geen regelafbreking voor de openingshaak.
• regelafbreking na het openen van de brace.
• regelafbreking vóór het sluiten van de brace.
• regelafbreking na de sluitende brace, alleen als die brace een statement of de body van een methode, constructor of benoemde klasse beëindigt. Er is bijvoorbeeld geen regelafbreking na de brace als deze wordt gevolgd door else of een komma.

voorbeelden:

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

enkele uitzonderingen voor enum klassen worden gegeven in Paragraaf 4.8.1,Enum klassen.

4.1.3 lege blokken: kan beknopt zijn

een leeg blok of een blokachtige constructie kan in K & r-stijl zijn (zoals beschreven insectie 4.1.2). Als alternatief kan het onmiddellijk na het openen worden gesloten, zonder tekens of regelafbreking ertussen ({}), tenzij het deel uitmaakt van een multi-block statement (één die direct meerdere blokken bevat:if/else oftry/catch/finally).

voorbeelden:

 // 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) {}

: + 2 spaties

elke keer dat een nieuw blok of een blokachtige constructie wordt geopend, neemt het inspringen met twee spaties toe. Wanneer het blok eindigt, keert de inspringing terug naar het vorige inspringingniveau. Het inspringniveau is van toepassing op zowel code als commentaar in het hele blok. (Zie het voorbeeld in Paragraaf 4.1.2,niet-lege blokken: K & R stijl.)

4.3 Eén statement per regel

elk statement wordt gevolgd door een regeleinde.

4.4 Kolomlimiet: 100

Java-code heeft een kolomlimiet van 100 tekens. Een “karakter” betekent elk Unicode-codepunt.Behalve zoals hieronder vermeld, moet elke regel die deze limiet zou overschrijden, worden omwikkeld met een regel, zoals uitgelegd in sectie 4.5, omwikkeling met een regel.

elk Unicode-codepunt telt als één teken, zelfs als de weergavebreedte groter of kleiner is. Als u bijvoorbeeld volledige tekens gebruikt, kunt u ervoor kiezen om de regel eerder af te wikkelen dan waar deze regel strikt vereist.

uitzonderingen:

1. regels waarbij het niet mogelijk is om de kolomlimiet te volgen (bijvoorbeeld een lange URL in Javadoc, of een lange JSNI methode referentie).
2. package en import verklaringen (zie paragraaf 3.2 Package statement en 3.3 import statements).
3. commandoregels in een opmerking die in een shell kan worden geknipt en geplakt.

4.5 regelafbreking

terminologie Opmerking: Wanneer code die anders wettelijk een enkele regel zou kunnen bevatten in meerdere regels is verdeeld, wordt deze activiteit regelafbreking genoemd.

er is geen uitgebreide, deterministische formule die precies laat zien hoe regelafbreking in elke situatie moet worden uitgevoerd. Heel vaak zijn er verschillende geldige manieren om hetzelfde stukje code te wikkelen.

opmerking: hoewel de typische reden voor regelafbreking is om het overlopen van de kolomlimiet te vermijden, kan zelfs code die in feite binnen de kolomlimiet zou passen, naar goeddunken van de auteur met regelafbreking worden omwikkeld.

Tip: het extraheren van een methode of lokale variabele kan het probleem oplossen zonder de noodzaak om line-wrap.

4.5.1 waar te breken

de eerste richtlijn van regelafwikkeling is: liever breken op een hoger syntactisch niveau. Ook:

1. wanneer een regel wordt verbroken bij een niet-toegewezen operator, komt de pauze voor het symbool. (Merk op dat dit niet dezelfde praktijk wordt gebruikt in Google stijl voor andere talen, zoals C++ en JavaScript.)
   • Dit geldt ook voor de volgende “operator-achtige” symbolen:
     • het puntscheidingsteken (.)
     • De twee dubbele punten van een methodenreferentie (::)
     • een ampersand in een typegebonden (<T extends Foo & Bar>)
     • a pipe in a catch block (catch (FooException | BarException e)).
2. wanneer een regel wordt verbroken bij een toegewezen operator komt de pauze meestal na het symbool, maar beide richtingen zijn aanvaardbaar.
   • Dit geldt ook voor de” assignment-operatorachtige ” dubbele punt in een verbeterdefor (“foreach”) statement.
3. een methode of constructornaam blijft verbonden aan het Open haakje (() dat volgt.
4. een komma (,) blijft bevestigd aan het token dat eraan vooraf gaat.
5. een lijn wordt nooit gebroken naast de pijl in een lambda, behalve dat een breuk direct na de pijl kan komen als het lichaam van de lambda bestaat uit een enkele uitdrukking. Voorbeelden:

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

opmerking: het primaire doel voor regelafbreking is om clearcode te hebben, niet noodzakelijk code die in het kleinste aantal regels past.

4.5.2 vervolgregels inspringen ten minste +4 spaties

bij regelafbreking wordt elke regel na de eerste (elke vervolgregel) ingesprongen op ten minste +4 van de oorspronkelijke regel.

wanneer er meerdere vervolglijnen zijn, kan de inspringing worden gevarieerd tot voorbij +4 zoals voorgeschreven. In het algemeen gebruiken twee vervolglijnen hetzelfde inspringniveau dan en alleen als ze beginnen met syntactisch parallelle elementen.

paragraaf 4.6.3 over horizontale uitlijning behandelt de ontmoedigde praktijk van het gebruik van een variabel aantal spaties om bepaalde tokens met vorige regels uit te lijnen.

4.6 witruimte

4.6.1 verticale witruimte

Er verschijnt altijd een enkele lege regel:

1. tussen opeenvolgende leden of initializers van een klasse: velden, constructors, methoden, geneste klassen, statische initializers, en instantie initializers.
   • uitzondering: een lege regel tussen twee opeenvolgende velden (met geen andere code ertussen) is optioneel. Dergelijke lege regels worden gebruikt als dat nodig is om logische groepen van velden te maken.
   • uitzondering: lege regels tussen enumconstanten worden behandeld in Paragraaf 4.8.1.
2. zoals vereist door andere secties van dit document (zoals sectie 3, Bronbestandstructuur en sectie 3.3, import statements).

een enkele lege regel kan ook overal verschijnen waar het de leesbaarheid verbetert, bijvoorbeeld tussenstatements om de code in logische subsecties te organiseren. Een lege regel voor het eerste lid of initializer, of na het laatste lid of initializer van de klasse, wordt noch aangemoedigd noch aangemoedigd.

meerdere opeenvolgende blanco regels zijn toegestaan, maar nooit vereist (of aangemoedigd).

4.6.2 horizontale witruimte

verder dan waar vereist door de taal-of andere stijlregels, en afgezien van literalen, commentaren en javadoc, verschijnt een enkele ASCII-ruimte ook alleen op de volgende plaatsen.

1. het Scheiden van een gereserveerd woord, zoals iffor of catch, van een haakje openen (() die volgt op die regel
2. het Scheiden van een gereserveerd woord, zoals else of catch, van een sluitaccolade (}) dat voorafgaat aan het op die regel
3. Voor alle open-accolade ({), met twee uitzonderingen:
   • @SomeAnnotation({a, b}) (er wordt geen spatie gebruikt)
   • String x = {{"foo"}}; (er is geen spatie vereist tussen {{, door item 8 hieronder)
4. aan beide zijden van een binaire of ternaire operator. Dit geldt ook voor de volgende” operator-achtige “symbolen:
   • De ampersand in een conjunctief type gebonden: <T extends Foo & Bar>
   • De Pijp voor een catch block die meerdere uitzonderingen afhandelt: catch (FooException | BarException e)
   • De dubbele punt (:) in een verbeterd for (“foreach”) statement
   • de pijl in een lambda-expressie: (String str) -> str.length()

   maar niet

   • de twee dubbele punten (::) van een referentie methode, die geschreven is als: Object::toString
   • de punt scheidingsteken (.), die is geschreven als object.toString()
5. Na ,:; of het haakje sluiten ()) van een gegoten
6. Op beide zijden van de dubbele slash (//) dat begint een einde-van-regel commentaar. Hier zijn meerdere spaties toegestaan, maar niet vereist.
7. Tussen het type en de variabele van een verklaring: List<String> list
8. Optioneel, net binnen de beide beugels van een array initialiseren
   • new int {5, 6} en new int { 5, 6 } zowel geldig
9. Tussen een type annotatie en of ....

deze regel wordt nooit geïnterpreteerd als het vereisen of verbieden van extra ruimte aan het begin of aan het begin van een regel; het heeft alleen betrekking op binnenruimte.

4.6.3 horizontale uitlijning: nooit vereist

Terminologienotitie: Horizontale uitlijning is de praktijk van het toevoegen van een variabel aantal extra spaties in uw code met het doel van het maken van bepaalde tokens verschijnen direct onder bepaalde andere tokens op eerdere regels.

Deze praktijk is toegestaan, maar is nooit vereist door Google Style. Het is niet eens nodig om horizontale uitlijning te handhaven op plaatsen waar het al werd gebruikt.

Hier is een voorbeeld zonder uitlijning, dan met behulp van uitlijning:

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

Tip: uitlijning kan de leesbaarheid bevorderen, maar het creëert problemen voor toekomstig onderhoud. Overweeg een toekomstige verandering die slechts één lijn moet raken. Deze verandering kan de voorheen aangename opmaak verminkt laten, en dat is toegestaan. Meer vaakhet vraagt de coder (misschien u) om witruimte aan te passen op nabijgelegen lijnen ook, mogelijk triggering een trapsgewijze reeks van herformattings. Die één-regel verandering heeft nu een ” ontploffingsradius.”Dit kan in het slechtste geval resulteren in zinloos werk, maar in het beste geval corrumpeert het nog steeds versie historyinformatie, vertraagt reviewers en verergert fusieconflicten.

4.7 Groepeerhaakjes: aanbevolen

optionele groepeerhaakjes worden alleen weggelaten wanneer auteur en recensent het erover eens zijn dat er geen redelijke kans is dat de code verkeerd wordt geïnterpreteerd zonder deze haakjes, noch zouden zij de code gemakkelijker hebben gemaakt om te lezen. Het is niet redelijk om aan te nemen dat elke lezer de gehele javaoperator ranglijst heeft onthouden.

4.8 specifieke constructies

4.8.1 Enumklassen

Na elke komma die een enumconstante volgt, is een regeleinde optioneel. Extra blanklines (meestal slechts één) zijn ook toegestaan. Dit is een mogelijkheid:

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

een enum klasse zonder methoden en geen documentatie over zijn constanten kan optioneel worden geformatteerd als het een array initializer was (zie paragraaf 4.8.3.1 onarray initializers).

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

aangezien enum-klassen klassen zijn, zijn alle andere regels voor het formatteren van klassen van toepassing.

4.8.2 variabele declaraties

4.8.2.1 Eén variabele per declaratie

elke variabele declaratie (veld of lokaal) declareert slechts één variabele: declaraties zoalsint a, b; worden niet gebruikt.

uitzondering: Meerdere variabele declaraties zijn aanvaardbaar in de header van eenfor lus.

4.8.2.2 gedeclareerd indien nodig

lokale variabelen worden niet gewoonlijk gedeclareerd aan het begin van hun containingblock of block-achtige constructie. In plaats daarvan worden lokale variabelen gedeclareerd dicht bij het punt waar ze voor het eerst worden gebruikt (binnen redelijkheid), om hun scope te minimaliseren. Lokale variabele declaraties hebben doorgaans initializers, of worden onmiddellijk na declaratie geïnitialiseerd.

4.8.3 Arrays

4.8.3.1 Array initializers: kan ” block-like “

zijn elke array initializer kan optioneel worden geformatteerd alsof het een ” block-like construct.”Bijvoorbeeld, de volgende zijn allemaal geldig (geen limitatieve lijst):

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 Geen C-stijl array declaraties

De vierkante haakjes vormen een deel van het type, niet de variabele:String args, nietString args.

4.8.4 switch statements

terminologie opmerking: in de accolades van een schakelblok zitten een of meer statementgroepen. Elke statementgroep bestaat uit één of meer schakellabels (ofwel case FOO: ofdefault:), gevolgd door één of meer statements (of, voor de laatste statementgroep, nul of meer statements).

4.8.4.1 inspringen

net als bij elk ander blok is de inhoud van een schakelblok ingesprongen +2.

na een schakellabel is er een regelafbreking en wordt het inspringniveau +2 verhoogd, precies zoals bij het openen van een blok. Het volgende schakellabel keert terug naar het vorige inspringniveau, alsof een blok gesloten was.

4.8.4.2 doorval:

binnen een schakelblok wordt elke statementgroep ofwel abrupt beëindigd (met eenbreakcontinuereturn of gegooid uitzondering), of wordt gemarkeerd met een commentaar om aan te geven dat de uitvoering zal of zou kunnen doorgaan in de volgende statementgroep. Elk commentaar dat het idee van fall-through communiceert is voldoende (meestal// fall through). Deze speciale opmerking is niet vereist inde laatste statement groep van het schakelblok. Bijvoorbeeld:

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

merk op dat er geen commentaar nodig is na case 1:, alleen aan het einde van de statement-groep.

4.8.4.3 hetdefault geval is aanwezig

elk switch statement bevat een default statementgroep, zelfs als het geen code bevat.

uitzondering: een switch statement voor een enum type mag de default statement groep weglaten, als het expliciete gevallen bevat die alle mogelijke waarden van dat type bestrijken. Dit stelt IDEs of andere statischanalysetools in staat om een waarschuwing te geven als er gevallen werden gemist.

4.8.5 annotaties

annotaties die van toepassing zijn op een klasse, methode of constructor verschijnen onmiddellijk na het documentatieblok, en elke annotatie wordt op een eigen regel vermeld (dat wil zeggen één annotatieper regel). Deze regeleinden vormen geen regelafbreking (Paragraaf4.5, regelafbreking), dus het inspringniveau wordt niet verhoogd. Voorbeeld:

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

uitzondering: Een enkele parameterless annotationmay in plaats daarvan verschijnt samen met de eerste regel van de handtekening, bijvoorbeeld:

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

Aantekeningen van toepassing is op een veld ook onmiddellijk na de documentatie te blokkeren, maar informatie het geval, meerdere aantekeningen (eventueel parameters) kan worden vermeld op dezelfde lijn, bijvoorbeeld:

@Partial @Mock DataLoader loader;

Er zijn geen specifieke regels voor de opmaak van annotaties op parameters, lokale variabelen, of typen.

in deze sectie worden implementatiecommentaren behandeld. Javadoc wordt afzonderlijk behandeld insectie 7, Javadoc.

elke regelafbreking kan worden voorafgegaan door willekeurige witruimte, gevolgd door een implementatiecommentaar.Zo ‘ n opmerking maakt de regel niet leeg.

4.8.6.1 Blokcommentaarstijl

Blokcommentaar wordt ingesprongen op hetzelfde niveau als de omringende code. Ze kunnen in/* ... */ stijl of// ... stijl. Voor multi-line/* ... */ opmerkingen, moeten volgende regels beginnen met* uitgelijnd met * op de vorige regel.

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

opmerkingen zijn niet ingesloten in vakjes met sterretjes of andere tekens.

Tip: gebruik bij het schrijven van meerregelige commentaren de/* ... */ stijl als u automatische codeopmaak wilt gebruiken om de regels te verwijderen indien nodig (alineastijl). De meeste opmaakregels worden niet opnieuw afgebroken in// ... stijlcommentaarblokken.

4.8.7 Modifiers

Class and member modifiers, indien aanwezig, verschijnen in de volgorde aanbevolen door de Java Language Specification:

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

4.8.8 numerieke Literalen

long – waarde integer literals gebruik een hoofdletter L achtervoegsel, nooit kleiner (om verwarring met het cijfer 1te voorkomen). Bijvoorbeeld, 3000000000Lin plaats van 3000000000l.

5 naamgeving

5.1 regels die voor alle identificatoren gelden

identificatiemiddelen gebruiken alleen ASCII-letters en-cijfers en, in een klein aantal hieronder vermelde gevallen, underscores. Elke geldige identifier komt dus overeen met de reguliere expressie\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.

klassenamen zijn typisch zelfstandige naamwoorden of zelfstandige zinnen. Bijvoorbeeld,Character ofImmutableList. Interfacenamen kunnen ook zelfstandige naamwoorden of uitdrukkingen zijn (bijvoorbeeld List), maar kunnen in plaats daarvan soms bijvoeglijke naamwoorden of bijvoeglijke naamwoorden bevatten (bijvoorbeeldReadable).

Er zijn geen specifieke regels of zelfs gevestigde conventies voor het benoemen van annotatietypen.

testklassen worden benoemd beginnend met de naam van de klasse die ze testen, en eindigend met Test. Bijvoorbeeld,HashTest ofHashIntegrationTest.

5.2.3 Methodenamen

Methodenamen worden in kleine letters geschreven.

Methodenamen zijn typisch werkwoorden of werkwoordzinnen. Bijvoorbeeld,sendMessage ofstop.

Underscores kunnen in JUnit-testmethode-namen voorkomen om logische componenten van de naam te scheiden, waarbij elk onderdeel in een kleine letters is geschreven.Een typisch patroon is <methodUnderTest>_<state>,bijvoorbeeld pop_emptyStack. Er is niemand correct om testmethoden te noemen.

5.2.4 constante namen

constante namen gebruik CONSTANT_CASE: alle hoofdletters, met elk woord gescheiden van het volgende door een enkele underscore. Maar wat is een constant precies?

constanten zijn statische eindvelden waarvan de inhoud zeer onveranderlijk is en waarvan de methoden nodetecteerbare bijwerkingen hebben. Dit omvat primitieven, Strings, onveranderlijke types, en onveranderlijke collecties van onveranderlijke types. Als een van de waarneembare toestand van de instantie kan veranderen, is het niet eenconstant. Alleen de bedoeling om het object nooit te muteren is niet genoeg. Bijvoorbeeld:

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

deze namen zijn typisch zelfstandige naamwoorden of zelfstandige zinnen.

5.2.5 niet-constante veldnamen

niet-constante veldnamen (statisch of anderszins) worden geschreven in kleine letters.

deze namen zijn typisch zelfstandige naamwoorden of zelfstandige zinnen. Bijvoorbeeld,computedValues ofindex.

5.2.6 parameternamen

parameternamen worden in kleine letters geschreven.

parameternamen van één letter in openbare methoden moeten worden vermeden.

5.2.7 namen van lokale variabelen

namen van lokale variabelen worden in kleine letters geschreven.

zelfs als finaal en onveranderlijk, worden lokale variabelen niet als constanten beschouwd en zouden ze niet als constanten moeten worden opgemaakt.

5.2.8 type variabele namen

elke type variabele wordt genoemd in een van twee stijlen:

• Een enkele hoofdletter, eventueel gevolgd door een enkel cijfer (zoals ETXT2)
• een naam in de voor klassen gebruikte vorm (zie paragraaf 5.2.2, klassenamen), gevolgd door de hoofdletter T (voorbeelden): RequestTFooBarT).

5.3 Camel-geval: gedefinieerd

soms is er meer dan één redelijke manier om een Engelse zin om te zetten in camel-geval,zoals wanneer acroniemen of ongebruikelijke constructies zoals “IPv6” of “iOS” aanwezig zijn. Om de voorspelbaarheid te verbeteren, Google Style specificeert de volgende (bijna) deterministische regeling.

beginnend met de prozavorm van de naam:

1. converteer de zin naar gewone ASCII en verwijder eventuele apostrofen. Bijvoorbeeld, “Müller’ s algoritme “zou kunnen worden”Muellers algoritme”.
2. verdeel dit resultaat in woorden, splitsen op spaties en eventuele resterende interpunctie (meestal koppeltekens).
   • aanbevolen: als een woord al een conventioneel camel-case-uiterlijk heeft in algemeen gebruik, splits dit in de samenstellende delen (bijvoorbeeld, “AdWords” wordt “ad words”). Merk op dat een woord als “iOS” niet echt in camel geval per se; het tart elke conventie, dus deze aanbeveling is niet van toepassing.
3. nu kleine letters alles (inclusief acroniemen), dan hoofdletters alleen het eerste teken van:
   • … elk woord, om hogere camel case op te leveren, of
   • … elk woord behalve het eerste, om een lager camel-geval
4. te geven, voeg tot slot alle woorden samen in een enkele identifier.

merk op dat het omhulsel van de oorspronkelijke woorden vrijwel geheel buiten beschouwing wordt gelaten. Bijvoorbeeld:

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: altijd gebruikt

een methode wordt gemarkeerd met de @Override annotatiewanneer het legaal is. Dit omvat een klasse methode die een superclass methode overschrijft, een klasse methode die een interface methode implementeert, en een interface methode die een superinterfacemethod respecteert.

uitzondering:@Override mag worden weggelaten als de moedermethode@Deprecatedis.

6.2 gevangen uitzonderingen: niet genegeerd

behalve zoals hieronder vermeld, is het zeer zelden correct om niets te doen als reactie op een gevangenexceptie. (Typische antwoorden zijn om het te loggen, of als het als “onmogelijk” wordt beschouwd, het opnieuw te tekenen als eenAssertionError.)

wanneer het echt passend is om geen enkele actie te ondernemen in een vangstblok, wordt de reden waarom dit gerechtvaardigd is uitgelegd in een commentaar.

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

uitzondering: in tests kan een gevangen uitzondering worden ontkend zonder commentaar als zijn naam is of begint metexpected. Het volgen is een veel voorkomende idioom om ervoor te zorgen dat de code te testen doet gooien een uitzondering van het verwachte type, dus een commentaar is hier niet nodig.

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

6.3 Static members: qualified using class

wanneer een verwijzing naar een static class member moet worden gekwalificeerd, wordt het gekwalificeerd met de naam van die klasse, niet met een verwijzing of expressie van het type van die klasse.

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

6.4 Finalizers: niet gebruikt

Het is uiterst zeldzaam omObject.finalizete overschrijven.

Tip: niet doen. Als je absoluut moet, lees en begrijp effectief Java Item 7, “vermijd Finalizers,” zeer zorgvuldig, en doe het dan niet.

7 Javadoc

7.1 opmaak

7.1.1 algemene vorm

De basisopmaak van Javadoc blokken is zoals te zien in dit voorbeeld:

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

… of in dit voorbeeld met één regel:

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

de basisvorm is altijd aanvaardbaar. De single-line formulier kan worden vervangen wanneer het geheel van het Javadoc blok (inclusief commentaar markers) kan passen op een enkele regel. Merk op dat dit alleen van toepassing is als er geen blok tags zijn zoals @return.

7.1.2 alinea ‘ s

een lege regel—dat wil zeggen een regel met alleen de uitgelijnde sterretje(*)—verschijnt tussen alinea ‘ s en vóór de groep blok-tags ifpresent. Elke alinea maar de eerste heeft <p> vlak voor het eerste woord,zonder spatie erna.

7.1.3 blok-tags

elke standaard “blok-tags” die worden gebruikt, verschijnt in de volgorde@param@return@throws@deprecated, en deze vier typen nooit verschijnen met een lege beschrijving. Als een blok-tag niet op een enkele regel past, worden continueringsregels ingesprongen met vier (of meer) spaties vanaf de positie van de @.

7.2 het samenvattingsfragment

elk Javadoc-blok begint met een kort samenvattingsfragment. Dit fragment is zeer belangrijk: het is het enige deel van de tekst dat in bepaalde contexten verschijnt, zoals klassen-en methodeindexen.

Dit is een fragment—een zelfstandig naamwoord of werkwoordzin, geen volledige zin. Het begint niet met A {@code Foo} is a..., ofThis method returns..., noch vormt het een complete imperatief sentencelike Save the record.. Echter, het fragment is hoofdletter enpunctuated alsof het een volledige zin.

Tip: een veel voorkomende fout is het schrijven van eenvoudige Javadoc in de vorm/** @return the customer ID */. Dit is onjuist en moet worden gewijzigd naar /** Returns the customer ID. */.

7.3 Waar Javadoc minimaal

wordt gebruikt, is Javadoc aanwezig voor elkepublic klasse, en elkepublic ofprotected lid van een dergelijke klasse, met een paar uitzonderingen hieronder.

aanvullende Javadoc-inhoud kan ook aanwezig zijn, zoals uitgelegd in Paragraaf 7.3.4, niet-vereiste Javadoc.

7.3.1 uitzondering: zelfverklarende methoden

Javadoc is optioneel voor “eenvoudige, voor de hand liggende” methoden zoalsgetFoo, in gevallen waarin er echt en echt niets anders de moeite waard is om te zeggen, maar “geeft de foo”.

belangrijk: het is niet passend om deze uitzondering aan te halen als rechtvaardiging voor relevante informatie die een doorsnee lezer wellicht moet weten. Bijvoorbeeld, voor een methode genaamd getCanonicalName, laat de documentatie niet weg(met de reden dat het alleen/** Returns the canonical name. */ zou zeggen) als een typische lezer geen idee heeft wat de term “canonieke naam” betekent!

7.3.2 uitzondering: overschrijvingen

Javadoc is niet altijd aanwezig op een methode die een supertype methode overschrijft.

7.3.4 niet-vereiste Javadoc

andere klassen en leden hebben Javadoc indien nodig of gewenst.