1 Introduktion

detta dokument fungerar som den fullständiga definitionen av Googles kodningsstandarder forsource-kod i programmeringsspråket Java Kubi. En Java – källfil beskrivs som inGoogle-stil om och endast om den följer reglerna häri.

liksom andra programmeringsstilguider spänner de frågor som omfattas inte bara estetiska problem avformatering, men andra typer av konventioner eller kodningsstandarder också. Detta dokument fokuserar emellertid främst på de hårda och snabba regler som vi följer universellt och undviker att ge råd som inte är tydligt verkställbara (vare sig det är mänskligt eller verktyg).

1.1 terminologi anteckningar

i detta dokument, om inte annat klargörs:

1. termen klass används inkluderande för att betyda en ”vanlig” klass, enum klass, gränssnitt eller annoteringstyp (@interface).
2. termen medlem (i en klass) används inkluderande för att betyda en kapslad klass, fält, metod eller konstruktör; det vill säga Allt innehåll på toppnivå i en klass utom initialiserare och kommentarer.
3. termen kommentar hänvisar alltid till implementeringskommentarer. Vi använder inte frasen ”dokumentationskommentarer”, utan använder den gemensamma termen ” Javadoc.”

andra” terminologianteckningar ” visas ibland i hela dokumentet.

1.2 Guideanteckningar

exempelkod i detta dokument är icke-normativ. Det vill säga, medan exemplenär i Google-stil, kanske de inte illustrerar det enda snygga sättet att representerakod. Valfria formateringsval som görs i exempel bör inte verkställas som regler.

2 källfilens grunder

2.1 filnamn

källfilens namn består av det skiftlägeskänsliga namnet på den toppklass som den innehåller(av vilken det finns exakt en), plus.java -tillägget.

2.2 filkodning: UTF-8

källfiler kodas i UTF-8.

2.3 specialtecken

2.3.1 blanktecken

bortsett från radterminatorsekvensen är ASCII horisontell spacecharacter (0x20) det enda blanktecken som visas någonstans i en källfil. Detta innebär att:

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) Fly.

2.3.3 icke-ASCII-tecken

för de återstående icke-ASCII-tecknen används antingen det faktiska Unicode-tecknet(t.ex. ∞) eller motsvarande Unicode escape(t. ex. \u221e). Valet beror bara påvilket gör koden lättare att läsa och förstå, även om Unicode escapesutanför strängbokstäver och kommentarer är starkt avskräckta.

tips: i Unicode escape-fallet, och ibland även när actualUnicode-tecken används, kan en förklarande kommentar vara till stor hjälp.

exempel:

String unitAbbrev = "μs";

exempel	diskussion
bäst: helt klart även utan kommentar.
String unitAbbrev = "\u03bcs"; // "μs"	tillåtet, men det finns ingen anledning att göra detta.
String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"	tillåtet, men besvärligt och benäget för misstag.
String unitAbbrev = "\u03bcs";	Dålig: läsaren har ingen aning om vad det här är.
return '\ufeff' + content; // byte order mark	bra: använd escapes för icke-utskrivbara tecken och kommentera vid behov.

Tips: Gör aldrig din kod mindre läsbar helt enkelt av rädsla för attvissa program kanske inte hanterar icke-ASCII-tecken ordentligt. Om det skulle hända, är deprogrammen trasiga och de måste åtgärdas.

3 Källfilstruktur

exakt en tom rad separerar varje avsnitt som är närvarande.

3.1 licens-eller upphovsrättsinformation, om den finns

om licens-eller upphovsrättsinformation hör hemma i en fil, hör den här.

3.2 package statement

package statement är inte radinslaget. Kolumngränsen (Avsnitt 4.4, Kolumngräns: 100) gäller inte paketdeklarationer.

3.3 importdeklarationer

3.3.1 ingen jokertecken import

jokertecken import, statisk eller på annat sätt, används inte.

3.3.2 ingen radförpackning

importdeklarationer är inte radförpackade. Kolumngränsen (Avsnitt 4.4, Kolumngräns: 100) gäller inte importuttalanden.

3.3.3 beställning och avstånd

import beställs enligt följande:

1. all statisk import i ett enda block.
2. all icke-statisk import i ett enda block.

om det finns både statisk och icke-statisk import, separerar en enda tom rad de två blocken. Det finns inga andra tomma rader mellan importdeklarationer.

inom varje block visas de importerade namnen i ASCII-sorteringsordning. (OBS: Detta är inte samma sak som import uttalanden är i ASCII sorteringsordning, eftersom ’.’sorterar före’;’.)

3.3.4 ingen statisk import för klasser

statisk import används inte för statiska kapslade klasser. De importeras mednormal import.

3.4 Klassdeklaration

3.4.1 exakt en klassdeklaration på toppnivå

varje klass på toppnivå finns i en egen källfil.

3, 4.2 beställning av klassinnehåll

den ordning du väljer för medlemmarna och initialiserarna i din klass kan ha stor effekt på läsbarhet. Det finns dock inget enda korrekt recept på hur man gör det; olika klasser kanbeställa innehållet på olika sätt.

vad som är viktigt är att varje klass använder någon logisk ordning, vilket itsmainer kan förklara om du blir frågad. Till exempel läggs nya metoder inte bara vanligtvis till i slutet av klassen, eftersom det skulle ge ”kronologisk efter datum tillagd” beställning, vilket inte är en logiskordning.

3.4.2.1 överbelastning: dela aldrig

När en klass har flera konstruktörer eller flera metoder med samma namn visas dessa i följd, utan någon annan kod däremellan (inte ens privata medlemmar).

4 formatering

terminologi Obs: blockliknande konstruktion hänvisar tillkroppen av en klass, metod eller konstruktör. Observera att, genom avsnitt 4.8.3.1 onarray initializers, någon array initializerkan eventuellt behandlas som om det vore en blockliknande konstruktion.

4.1 hängslen

4.1.1 hängslen används där valfria

hängslen används medifelsefordo ochwhile uttalanden, även när kroppen är tom eller innehåller endast ett enda uttalande.

4.1.2 nonempty blocks: K& r style

hängslen följ Kernighan och Ritchie-stilen(”egyptiska parenteser”)för nonempty block och blockliknande konstruktioner:

• ingen radbrytning före öppningsstödet.
• Linjebrytning efter öppningsstödet.
• radbrytning före stängningen.
• radbrytning efter stängningsstödet, endast om det stag avslutar ett uttalande eller avslutar kroppen av en metod, konstruktör eller namngiven klass. Till exempel finns det ingen radbrytning efter staget om det följs av else eller ett komma.

exempel:

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

några undantag för enum-klasser ges i avsnitt 4.8.1,Enum-klasser.

4.1.3 tomma block: kan vara kortfattad

ett tomt block eller blockliknande konstruktion kan vara i k & r-stil (som beskrivs i avsnitt 4.1.2). Alternativt kan det stängas omedelbartefter att det har öppnats, utan tecken eller radbrytning däremellan({}), såvida det inte ingår i amulti-block-uttalandet (ett som direkt innehåller flera block:if/else ellertry/catch/finally).

exempel:

 // 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 Block indentation: + 2 mellanslag

varje gång ett nytt block eller blockliknande konstruktion öppnas ökar indraget med två utrymmen. När blocket slutar återgår indraget till föregående indragningsnivå. Indragnivångäller både kod och kommentarer i hela blocket. (Se exemplet i avsnitt 4.1.2,nonempty blocks: K & R Style.)

4.3 ett uttalande per rad

varje uttalande följs av en radbrytning.

4.4 Kolumngräns: 100

Java-kod har en kolumngräns på 100 tecken. Ett ”tecken” betyder vilken Unicode-kodpunkt som helst.Med undantag för vad som anges nedan måste varje rad som överskrider denna gräns lindas in, såsom förklaras i avsnitt 4.5, lindning.

varje Unicode-kodpunkt räknas som ett tecken, även om dess visningsbredd ärstörre eller mindre. Om du till exempel använder fullbreddstecken kan du välja att linda in raden tidigare än där denna regel strikt kräver.

undantag:

1. rader där det inte är möjligt att följa kolumngränsen (till exempel en lång URL i Javadoc eller en lång jsni-metodreferens).
2. package ochimport uttalanden (se avsnitt 3.2 paketdeklaration och 3.3 importdeklarationer).
3. kommandorader i en kommentar som kan klippas och klistras in i ett skal.

4.5 Line-wrapping

terminologi Obs: När kod som annars lagligen kan uppta en enda rad är uppdelad i flera rader kallas denna aktivitet Line-wrapping.

det finns ingen omfattande, deterministisk formel som visar exakt hur man linjer in i varje situation. Mycket ofta finns det flera giltiga sätt att radbryta samma kod.

Obs: medan den typiska orsaken till radinpackning är att undvikaöverflödande kolumngränsen, kan även kod som faktiskt passar in i kolumngränsen lindas efter författarens eget gottfinnande.

tips: att extrahera en metod eller lokal variabel kan lösa problemetutan att behöva radbrytas.

4.5.1 var man ska bryta

huvuddirektivet för radförpackning är: föredrar att bryta på enhögre syntaktisk nivå. Också:

1. när en rad bryts vid en icke-uppdragsoperatör kommer pausen före symbolen. (Observera att detta inte är samma praxis som används i Google style för andra språk, till exempel C++ och JavaScript.)
   • detta gäller även följande ”operatörsliknande” symboler:
     • punktseparatorn (.)
     • de två kolonerna i en metodreferens (::)
     • en ampersand i en typ bunden (<T extends Foo & Bar>)
     • ett rör i ett fångstblock (catch (FooException | BarException e)).
2. när en rad bryts vid en uppdragsoperatör kommer pausen vanligtvis efter symbolen, men båda hållen är acceptabel.
   • detta gäller även kolon ”tilldelning-operator-liknande” i en förbättrad for (”foreach”) uttalande.
3. en metod eller konstruktörnamn förblir kopplad till den öppna parentesen (() som följer den.
4. ett komma (,) förblir fäst vid token som föregår den.
5. en linje bryts aldrig intill pilen i en lambda, förutom att en paus kan komma omedelbart efter pilen om lambdas kropp består av ett enda obraced uttryck. Exempel:

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

Obs: Det primära målet för radinslagning är att ha clearcode, inte nödvändigtvis kod som passar i det minsta antalet rader.

4.5.2 indrag fortsättningslinjer minst + 4 mellanslag

När radinslagning, varje rad efter den första (varje fortsättningslinje) är indragen minst +4 från den ursprungliga raden.

När det finns flera fortsättningslinjer kan indrag varieras utöver +4 asdesired. I allmänhet använder två fortsättningslinjer samma indragningsnivå om och endast om debörja med syntaktiskt parallella element.

avsnitt 4.6.3 på horisontella inriktningsadresserden avskräckta praxisen att använda ett variabelt antal mellanslag för att anpassa vissa tokens med tidigare linjer.

4.6 Whitespace

4.6.1 vertikal Whitespace

en enda tom rad visas alltid:

1. mellan på varandra följande medlemmar eller initialiserare av en klass: fält, konstruktörer, metoder, kapslade klasser, statiska initialisatorer och instansinitialisatorer.
   • undantag: en tom rad mellan två på varandra följande fält (som inte har någon annan kod mellan dem) är valfri. Sådana tomma rader används vid behov för att skapa logiska grupperingar av fält.
   • undantag: tomma rader mellan enum-konstanter omfattas av avsnitt 4.8.1.
2. som krävs av andra delar av detta dokument (t.ex. avsnitt 3, Källfilstruktur och avsnitt 3.3, importdeklarationer).

en enda tom rad kan också visas var som helst det förbättrar läsbarheten, till exempel mellan uttalanden för att organisera koden i logiska underavsnitt. En tom rad före den första medlemmen eller initialiseraren, eller efter den sista medlemmen eller initialiseraren av klassen, uppmuntras varken nordiscouraged.

flera på varandra följande tomma rader är tillåtna, men krävs aldrig (eller uppmuntras).

4, 6.2 horisontell blanksteg

utöver vad som krävs av språket eller andra stilregler, och förutom bokstäver, kommentarer ochjavadoc, visas ett enda ASCII-utrymme endast på följande platser.

1. separera alla reserverade ord, till exempeliffor ellercatch, från en öppen parentes (() som följer den på den raden /li>
2. separera alla reserverade ord, till exempelelse ellercatch, från en avslutande lockig stag (}) som föregår det på den raden
3. innan någon öppen lockig stag ({), med två undantag:
   • @SomeAnnotation({a, b}) (inget mellanslag används)
   • String x = {{"foo"}}; (inget mellanslag krävs mellan {{, enligt punkt 8 nedan)
4. på båda sidor av en binär eller ternär operatör. Detta gäller även följande” operatörsliknande ” symboler:
   • Ampersand i en konjunktiv typ bunden:<T extends Foo & Bar>
   • röret för ett fångstblock som hanterar flera undantag: catch (FooException | BarException e)
   • kolon (:) I en förbättradfor (”foreach”) uttalande
   • pilen i ett lambda-uttryck: (String str) -> str.length()

   men inte

   • de två kolonerna (::) av en metodreferens, som är skriven som Object::toString
   • punktavskiljaren (.), som är skrivet som object.toString()
5. efter ,:; eller den avslutande parentesen ()) av en cast
6. på båda sidor av det dubbla snedstrecket (//) som börjar en end-of-line kommentar. Här är flera mellanslag tillåtna, men krävs inte.
7. mellan typ och variabel för en deklaration:List<String> list
8. valfritt precis inuti båda hängslen i en array initializer
   • new int {5, 6} ochnew int { 5, 6 } är båda giltiga
9. mellan en typanteckning och eller....

denna regel tolkas aldrig som att kräva eller förbjuda ytterligare utrymme i början av en rad; den behandlar endast inre utrymme.

4.6.3 horisontell inriktning: aldrig krävs

terminologi Obs: Horisontell inriktning äröva att lägga till ett variabelt antal ytterligare mellanslag i din kod med målet att göravissa tokens visas direkt under vissa andra tokens på tidigare rader.

denna praxis är tillåten, men krävs aldrig av Google Style. Det är inteäven nödvändigt att upprätthålla horisontell inriktning på platser där den redan användes.

Här är ett exempel utan justering, sedan använda justering:

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

tips: justering kan underlätta läsbarhet, men det skapar problem forfuture underhåll. Tänk på en framtida förändring som behöver röra bara en rad. Denna förändring kanlämna den tidigare tilltalande formateringen mangled, och det är tillåtet. OftareDet uppmanar kodaren (kanske du) att justera blankutrymme på närliggande linjer också, möjligtriggering en kaskad serie omformateringar. Den enradiga förändringen har nu en ” sprängradie.”Detta kan i värsta fall leda till meningslöst upptaget arbete, men i bästa fall korrumperar det fortfarande versionshistorikinformation, saktar ner granskare och förvärrar sammanslagningskonflikter.

4.7 gruppera parenteser: rekommenderade

valfria grupperingsparenteser utelämnas endast när författare och granskare är överens om att det inte finns någon rimlig chans att koden kommer att misstolkas utan dem, och de skulle inte heller ha gjort koden lättare att läsa. Det är inte rimligt att anta att varje läsare har hela Javaoperator-prioritetstabellen memorerad.

4.8 specifika konstruktioner

4.8.1 Enum-klasser

Efter varje komma som följer en enum-konstant är en radbrytning valfri. Ytterligare blanklines (vanligtvis bara en) är också tillåtna. Detta är en möjlighet:

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

en enum-klass utan metoder och ingen dokumentation om dess konstanter kan eventuellt formateras om det var en array-initialiserare (se avsnitt 4.8.3.1 onarray-initialiserare).

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

eftersom enum-klasser är klasser gäller alla andra regler för formatering av klasser.

4.8.2 Variabla deklarationer

4.8.2.1 en variabel per deklaration

varje variabel deklaration (fält eller lokal) deklarerar endast en variabel: deklarationer somint a, b; används inte.

undantag: Flera variabla deklarationer är acceptabla i rubriken för enfor loop.

4.8.2.2 deklareras vid behov

lokala variabler deklareras inte vanligtvis i början av deras innehållsblock eller blockliknande konstruktion. Istället deklareras lokala variabler nära den punkt de först används (inom förnuft) för att minimera deras omfattning. Lokala variabla deklarationer har vanligtvis initialiserare, eller initialiseras omedelbart efter deklarationen.

4.8.3 arrayer

4.8.3.1 Array initialisatorer: kan vara”block-liknande ”

varje array initializer kan eventuellt formateras som om det vore en ” block-likeconstruct.”Till exempel är följande alla giltiga (inte en 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 inga C-style array-deklarationer

hakparenteserna utgör en del av typen, inte variabeln:String args, inteString args.

4.8.4 byta uttalanden

terminologi Obs: inuti hängslen i aswitch block finns en eller flera uttalande grupper. Varje uttalande grupp består aven eller flera omkopplingsetiketter (antingen case FOO: ellerdefault:), följt av en eller flera uttalanden (eller, för den sista uttalande gruppen, noll eller flera uttalanden).

4.8.4.1 indrag

som med alla andra block är innehållet i ett omkopplarblock indraget +2.

efter en omkopplingsetikett finns det en radbrytning och indragningsnivån ökas +2 exaktsom om ett block öppnades. Följande omkopplingsetikett återgår till föregående indragnivå, som om ett block hade stängts.

4.8.4.2 falla igenom: kommenterade

inom ett switchblock avslutas varje uttalande grupp antingen abrupt (med ettbreakcontinuereturn eller kastat undantag), eller markeras med en kommentarför att indikera att utförandet kommer eller kan fortsätta till nästa uttalande grupp. Anycomment som kommunicerar tanken på fall-through är tillräcklig (typiskt// fall through). Denna speciella kommentar krävs inte iDen sista uttalande gruppen av switchblocket. Exempel:

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

Observera att ingen kommentar behövs eftercase 1:, barai slutet av uttalande gruppen.

4.8.4.3default case är närvarande

varje switch-sats innehåller ettdefault statementgroup, även om det inte innehåller någon kod.

undantag: ett omkopplingsuttalande för enenum – typ kan utelämnadefault – grupp, om det inkluderarexplicita fall som täcker alla möjliga värden av den typen. Detta gör det möjligt för IDEs eller andra staticanalysis verktyg för att utfärda en varning om några fall missades.

4.8.5 anteckningar

anteckningar som gäller för en klass, metod eller konstruktör visas omedelbart efterdokumentationsblocket, och varje anteckning är listad på en egen rad (det vill säga en annotationper-rad). Dessa radbrytningar utgör inte linjeförpackning (Avsnitt4.5, Linjeförpackning), så indragningsnivån är inteökad. Exempel:

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

undantag: En enda parameterlös annoteringkan istället visas tillsammans med signaturens första rad, till exempel:

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

anteckningar som gäller för ett fält visas också omedelbart efter dokumentationsblocket, men idet här fallet kan flera anteckningar (eventuellt parametrerade) listas på samma rad;till exempel:

@Partial @Mock DataLoader loader;

det finns inga specifika regler för formatering av anteckningar om parametrar, lokala variabler eller typer.

detta avsnitt behandlar implementeringskommentarer. Javadoc adresseras separat isektion 7, Javadoc.

varje radbrytning kan föregås av godtyckligt mellanslag följt av en implementeringskommentar.En sådan kommentar gör linjen icke-tom.

4.8.6.1 blockkommentarstil

Blockkommentarer är indragna på samma nivå som den omgivande koden. De kan vara i/* ... */ style eller// ... style. För multi-line/* ... */ kommentarer måste efterföljande rader börja med* I linje med * på föregående rad.

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

kommentarer bifogas inte i rutor ritade med asterisker eller andra tecken.

Tips: när du skriver kommentarer med flera rader, använd/* ... */ stil om du vill ha automatiska kodformatterare tore-wrap raderna vid behov (styckestil). De flesta formatters inte åter wrap linjer i// ... stil kommentar block.

4.8.7 modifierare

klass-och medlemsmodifierare, när de finns, visas i ordningenrekommenderas av Java-språkspecifikationen:

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

4.8.8 numeriska bokstäver

long-värderade heltal bokstav använd en stor bokstav L suffix, neverlowercase (för att undvika förvirring med siffran 1). Till exempel 3000000000Lsnarare än 3000000000l.

5 Namngivning

5.1 regler som är gemensamma för alla identifierare

identifierare använder endast ASCII-bokstäver och siffror och, i ett litet antal fall som anges nedan, understryker. Således matchas varje giltigt identifieringsnamn med det reguljära uttrycket\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.

klassnamn är vanligtvis substantiv eller substantivfraser. Till exempelCharacter ellerImmutableList. Gränssnittsnamn kan också vara substantiv ellerunfraser (till exempel List), men kan ibland varaadjektiv eller adjektivfraser istället (till exempelReadable).

det finns inga specifika regler eller till och med väletablerade konventioner för namngivning av anteckningstyper.

testklasser heter börjar med namnet på den klass de testar och slutar med Test. Till exempelHashTest ellerHashIntegrationTest.

5.2.3 metodnamn

metodnamn skrivs i lowerCamelCase.

metodnamn är vanligtvis verb eller verbfraser. Till exempelsendMessage ellerstop.

understreck kan visas i JUnit testmetodnamn för att separera logiska komponenter i thename, med varje komponent skriven i lowerCamelCase.Ett typiskt mönster är <methodUnderTest>_<state>, till exempel pop_emptyStack. Det finns ingen Korrektsätt att namnge testmetoder.

5.2.4 konstanta namn

konstanta namn använd CONSTANT_CASE: alla stora bokstäver, med varje ord separerat från nästa med ett enda understreck. Men vad är aconstant, exakt?

konstanter är statiska slutfält vars innehåll är djupt oföränderligt och vars metoder har nodetectable biverkningar. Detta inkluderar primitiva, strängar, oföränderliga typer och oföränderligasamlingar av oföränderliga typer. Om någon av instansens observerbara tillstånd kan förändras är det inte konstant. Att bara ha för avsikt att aldrig mutera objektet räcker inte. Exempel:

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

dessa namn är vanligtvis substantiv eller substantivfraser.

5.2.5 icke-konstanta fältnamn

icke-konstanta fältnamn (statiska eller på annat sätt) skrivs i lowerCamelCase.

dessa namn är vanligtvis substantiv eller substantivfraser. Till exempelcomputedValues ellerindex.

5.2.6 parameternamn

parameternamn skrivs i lowerCamelCase.

parameternamn med ett tecken i offentliga metoder bör undvikas.

5.2.7 lokala variabelnamn

lokala variabelnamn skrivs i lowerCamelCase.

även när slutliga och oföränderliga, lokala variabler anses inte vara konstanter, och bör inte utformas som konstanter.

5.2.8 typvariabelnamn

varje typvariabel heter i en av två stilar:

• en enda bokstav, eventuellt följt av en enda siffra (t. ex. ETXT2)
• ett namn i den form som används för klasser (se avsnitt 5.2.2, klassnamn), följt av versaler T (exempel: RequestTFooBarT).

5.3 Camel case: definierat

ibland finns det mer än ett rimligt sätt att konvertera en engelsk fras till kamelfall,till exempel när akronymer eller ovanliga konstruktioner som ”IPv6” eller ”iOS” är närvarande. För att förbättraförutsägbarhet anger Google Style följande (nästan) deterministiska schema.

börjar med prosaformen av namnet:

1. konvertera frasen till vanlig ASCII och ta bort eventuella apostrofer. Till exempel kan” m Acriller ’ s algorithm ”bli”Muellers algorithm”.
2. dela detta resultat i ord, dela på mellanslag och eventuella återstående skiljetecken (vanligtvis bindestreck).
   • rekommenderas: om något ord redan har ett konventionellt kamelfall i vanligt bruk, dela upp detta i dess beståndsdelar (t.ex. ”AdWords” blir ”ad words”). Observera att ett ord som ”iOS” inte är riktigt i kamelfall i sig; det trotsar någon konvention, så denna rekommendation gäller inte.
3. nu gemener allt (inklusive akronymer), sedan versaler bara det första tecknet på:
   • … varje ord, för att ge upper camel case, eller
   • … varje ord utom det första, för att ge lägre kamelfall
4. slutligen, gå med alla orden i en enda identifierare.

Observera att höljet på de ursprungliga orden nästan helt ignoreras. Exempel:

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: använd alltid

en metod är markerad med@Override annoteringnär det är lagligt. Detta inkluderar en klassmetod som åsidosätter en superklassmetod, en klassmetodimplementerar en gränssnittsmetod och en gränssnittsmetod som respekterar en superinterfacemetod.

undantag:@Overridekan utelämnas när den överordnade metoden är@Deprecated.

6.2 fångade undantag: ignoreras inte

förutom som anges nedan är det mycket sällan korrekt att göra ingenting som svar på en caughtexception. (Typiska svar är att logga det, eller om det anses vara ”omöjligt”, ompröva det som ettAssertionError.)

När det verkligen är lämpligt att inte vidta några åtgärder i ett fångstblock, förklaras anledningen till att detta är motiverat i en kommentar.

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

undantag: i tester kan ett fångat undantag ignoreras utan kommentar om namnet är eller börjar medexpected. Thefollowing är ett mycket vanligt idiom för att säkerställa att koden som testas kastar anexception av den förväntade typen, så en kommentar är onödig här.

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

6.3 statiska medlemmar: kvalificerade med klass

När en referens till en statisk klassmedlem måste vara kvalificerad är den kvalificerad med klassens namn, inte med en referens eller ett uttryck av klassens typ.

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

6.4 Finalizers: används inte

det är extremt sällsynt att åsidosätta Object.finalize.

tips: gör det inte. Om du absolut måste, först läsa och förstå effektiv Java punkt 7,”Undvik Finalizers,” mycket noga, och sedan inte göra det.

7 Javadoc

7.1 formatering

7.1.1 allmän form

den grundläggande formateringen av Javadoc-block ses i detta exempel:

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

… eller i detta enkelradiga exempel:

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

grundformuläret är alltid acceptabelt. Enradsformuläret kan ersättas när entiretyof Javadoc-blocket (inklusive kommentarmarkörer) kan passa på en enda rad. Observera att detta endastgäller när det inte finns några blocktaggar som @return.

7.1.2 stycken

en tom rad—det vill säga en rad som endast innehåller den inriktade ledande asterisken(*) – visas mellan stycken och före gruppen av blocktaggar ompresentera. Varje stycke men den första har <p> omedelbart före det första ordet, utan mellanslag efter.

7.1.3 blockera taggar

någon av de vanliga ”blockera taggar” som används visas i ordningen@param@return@throws@deprecated, och dessa fyra typer aldrigvisas med en tom beskrivning. När en blocktagg inte passar på en enda rad, fortsättningsraderär indragna fyra (eller fler) mellanslag från positionen för @.

7.2 sammanfattningsfragmentet

varje Javadoc-block börjar med ett kort sammanfattningsfragment. Thisfragment är mycket viktigt: det är den enda delen av texten som visas i vissa sammanhang somklass-och metodindex.

detta är ett fragment-en substantivfras eller verbfras, inte en komplett mening. Det börjar inte med A {@code Foo} is a..., ellerThis method returns..., det bildar inte heller en fullständig imperativ sentencelike Save the record.. Fragmentet aktiveras dock ochpunkteras som om det var en fullständig mening.

tips: ett vanligt misstag är att skriva enkel Javadoc i formuläret/** @return the customer ID */. Detta är felaktigt, och borde varaändras till /** Returns the customer ID. */.

7.3 där Javadoc används

som minimum, Javadoc är närvarande för varjepublic klass, och varjepublic ellerprotected medlem av en sådan klass, med några undantagnoteras nedan.

ytterligare Javadoc-innehåll kan också finnas, vilket förklaras i avsnitt 7.3.4,icke-krävt Javadoc.

7.3.1 undantag: självförklarande metoder

Javadoc är valfritt för ”enkla, uppenbara” metoder somgetFoo, I de fall där det verkligen och verkligen äringet annat värt att säga men ”returnerar foo”.

viktigt: det är inte lämpligt att nämna detta undantag för att motivera relevant information som en typisk läsare kan behöva veta. Till exempel, för en metodnamed getCanonicalName, utelämna inte dokumentationen(med motiveringen att det bara skulle säga/** Returns the canonical name. */) om en typisk läsare kanske inte har någon ideawhat termen ”kanoniskt namn” betyder!

7.3.2 undantag: åsidosätter

Javadoc är inte alltid närvarande på en metod som åsidosätter en supertypmetod.

7.3.4 icke-nödvändig Javadoc

andra klasser och medlemmar har Javadoc efter behov eller önskemål.