1 Introduktion

dette dokument fungerer som den komplette definition af Googles kodningsstandarder for kildekode i Java-programmeringssproget. En Java-kildefil beskrives som værende inGoogle-stil, hvis og kun hvis den overholder reglerne heri.

ligesom andre programmeringsstilguider dækker problemerne ikke kun æstetiske problemer medformatering, men også andre typer konventioner eller kodningsstandarder. Dette dokument fokuserer dog primært på de hårde og hurtige regler, som vi følger universelt, ogundgår at give råd, der ikke klart kan håndhæves (hvad enten det er menneskeligt eller værktøj).

1.1 terminologi noter

i dette dokument, medmindre andet er præciseret:

1. udtrykket klasse bruges inklusivt til at betyde en “almindelig” klasse, enum klasse, grænseflade eller annotationstype (@interface).
2. udtrykket medlem (af en klasse) bruges inklusivt til at betyde en indlejret klasse, felt, metode eller konstruktør; det vil sige alt indhold på øverste niveau i en klasse undtagen initialisatorer og kommentarer.
3. udtrykket kommentar henviser altid til implementeringskommentarer. Vi bruger ikke udtrykket “dokumentationskommentarer”, i stedet for at bruge det almindelige udtryk ” Javadoc.”

andre” terminologinoter ” vises lejlighedsvis i hele dokumentet.

1.2 vejledning noter

eksempelkode i dette dokument er ikke-normativ. Det vil sige, mens eksemplerne er i Google-stil, illustrerer de muligvis ikke den eneste stilfulde måde at repræsenterekode. Valgfrie formateringsvalg foretaget i eksempler bør ikke håndhæves som regler.

2 grundlæggende kildefil

2.1 filnavn

kildefilnavnet består af det store og små bogstaver på den øverste klasse, den indeholder(hvoraf der er nøjagtigt en), plus.java udvidelse.

2.2 filkodning: UTF-8

kildefiler er kodet i UTF-8.

2.3 specialtegn

2.3.1 Hvidrumstegn

bortset fra linjeterminatorsekvensen er ASCII-vandret rumkarakter (0h20) det eneste hvide rumtegn, der vises overalt i en kildefil. Dette indebærer, at:

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

2.3.3 ikke-ASCII-tegn

for de resterende ikke-ASCII-tegn bruges enten det faktiske Unicode-tegn(f.eks. ∞) eller den tilsvarende Unicode escape(f. eks. \u221e). Valget afhænger kun afhvilket gør koden lettere at læse og forstå, selvom Unicode undslipperuden for strenglitteraler og kommentarer frarådes kraftigt.

Tip: i Unicode escape-sagen og lejlighedsvis, selv når actualUnicode-tegn bruges, kan en forklarende kommentar være meget nyttig.

eksempler:

eksempel	Diskussion
String unitAbbrev = "μs";	bedste: helt klart selv uden en kommentar.
String unitAbbrev = "\u03bcs"; // "μs"	tilladt, men der er ingen grund til at gøre dette.
String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"	tilladt, men akavet og tilbøjelig til fejl.
String unitAbbrev = "\u03bcs";	dårlig: læseren har ingen anelse om, hvad dette er.
return '\ufeff' + content; // byte order mark	god: brug escapes til tegn, der ikke kan udskrives, og kommenter om nødvendigt.

Tip: Gør aldrig din kode mindre læsbar simpelthen af frygt for, atnogle programmer håndterer muligvis ikke-ASCII-tegn korrekt. Hvis det skulle ske, er disse programmer brudt, og de skal løses.

3 Kildefilstruktur

præcis en tom linje adskiller hvert afsnit, der er til stede.

3.1 licens-eller ophavsretsoplysninger, hvis de findes

hvis licens-eller ophavsretsoplysninger hører til i en fil, hører de til her.

3.2 Pakkeerklæring

pakkeerklæringen er ikke linjeindpakket. Kolonnegrænsen (afsnit 4.4, Kolonnegrænse: 100) gælder ikke for pakkeerklæringer.

3.3 Import erklæringer

3.3.1 ingen import af jokertegn

import af jokertegn, statisk eller på anden måde, anvendes ikke.

3.3.2 ingen linjeindpakning

Importopgørelser er ikke linjeindpakket. Kolonnegrænsen (afsnit 4.4, Kolonnegrænsen: 100) gælder ikke for importangivelser.

3.3.3 bestilling og afstand

import bestilles som følger:

1. al statisk import i en enkelt blok.
2. Alle ikke-statiske import i en enkelt blok.

Hvis der er både statisk og ikke-statisk import, adskiller en enkelt tom linje de toblokke. Der er ingen andre tomme linjer mellem importopgørelser.

inden for hver blok vises de importerede navne i ASCII-sorteringsrækkefølge. (Bemærk: Dette er ikke det samme som importopgørelserne i ASCII-sorteringsrækkefølge, siden ‘.’sorterer før’;’.)

3.3.4 ingen statisk import til klasser

statisk import bruges ikke til statiske indlejrede klasser. De importeres mednormal import.

3.4 klassedeklaration

3.4.1 præcis en klassedeklaration på øverste niveau

hver klasse på øverste niveau findes i en egen kildefil.

3. 4.2 bestilling af klassens indhold

den rækkefølge, du vælger for medlemmerne og initialisatorerne af din klasse, kan have en stor effekt pålæring. Der er dog ingen enkelt korrekt opskrift på, hvordan man gør det; forskellige klasser kan bestille deres indhold på forskellige måder.

det, der er vigtigt, er, at hver klasse bruger en logisk rækkefølge, som densmaintainer kunne forklare, hvis han blev spurgt. For eksempel tilføjes nye metoder ikke kun sædvanligvis til slutningen af klassen, da det ville give “kronologisk efter dato tilføjet” bestilling, hvilket ikke er en logiskbestilling.

3.4.2.1 overbelastninger: opdel aldrig

Når en klasse har flere konstruktører eller flere metoder med samme navn, vises disse sekventielt uden anden kode imellem (ikke engang private medlemmer).

4 formatering

terminologi Bemærk: bloklignende konstruktion refererer tilkroppen af en klasse, metode eller konstruktør. Bemærk, at i henhold til afsnit 4.8.3.1 onarray initialisatorer, enhver array initialisatorkan eventuelt behandles som om det var en bloklignende konstruktion.

4.1 seler

4.1.1 seler bruges, hvor valgfri

seler bruges medifelsefordo ogwhile udsagn, selv nårkroppen er tom eller kun indeholder en enkelt erklæring.

4.1.2 ikke-tomme blokke: K & r-stil

seler følger Kernighan-og Ritchie-stilen (“Egyptiske parenteser”) til ikke-tomme blokke og bloklignende konstruktioner:

• ingen linjeskift før åbningsbøjlen.
• linjeskift efter åbningsbøjlen.
• linjeskift før lukkebøjlen.linjeskift efter lukkebøjlen, kun hvis bøjlen afslutter en erklæring eller afslutter kroppen af en metode, konstruktør eller navngivet klasse. For eksempel er der ingen linjeskift efter bøjlen, hvis den efterfølges af else eller et komma.

eksempler:

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

et par undtagelser for enum-klasser er angivet i afsnit 4.8.1,enum-klasser.

4.1.3 tomme blokke: kan være kortfattet

en tom blok eller bloklignende konstruktion kan være i K & r-stil (som beskrevet i afsnit 4.1.2). Alternativt kan den lukkes straksefter at den er åbnet, uden tegn eller linjeskift imellem({}), medmindre det er en del af amulti-block-sætningen (en der direkte indeholder flere blokke:if/else ellertry/catch/finally).

eksempler:

 // 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 indrykning: + 2 mellemrum

hver gang en ny blok eller bloklignende konstruktion åbnes, øges indrykket med Torum. Når blokken slutter, vender indrykket tilbage til det forrige indrykningsniveau. Indrykningsniveauetgælder for både kode og kommentarer i hele blokken. (Se eksemplet i afsnit 4.1.2, Nonempty blokke: K & r stil.)

4.3 en sætning pr.linje

hver sætning efterfølges af et linjeskift.

4.4 Kolonnegrænse: 100

Java-kode har en kolonnegrænse på 100 tegn. Et” tegn ” betyder ethvert Unicode-kodepunkt.Undtagen som anført nedenfor skal enhver linje, der overskrider denne grænse, være linjeindpakket som forklaret i Afsnit 4.5, Linjeindpakning.

hvert Unicode-kodepunkt tæller som et tegn, selvom dets visningsbredde er større eller mindre. For eksempel,hvis du bruger tegn med fuld bredde, kan du vælge at pakke linjen tidligere end hvor denne regel strengt kræver.

undtagelser:

1. linjer, hvor det ikke er muligt at overholde kolonnegrænsen (for eksempel en lang URL i Javadoc eller en lang jsni-metodereference).
2. package ogimport udsagn (se afsnit 3.2 pakke erklæring og 3.3 Import udsagn).
3. kommandolinjer i en kommentar, der kan klippes og indsættes i en skal.

4.5 Linjeindpakning

terminologi Bemærk: Når kode, der ellers lovligt kan optage en enkelt linje, er opdelt i flere linjer, kaldes denne aktivitetlinjeindpakning.

der er ingen omfattende, deterministisk formel, der viser præcis, hvordan man linjeindpakker ihver situation. Meget ofte er der flere gyldige måder at linieindpakke det samme stykke kode på.

Bemærk: mens den typiske årsag til linjeindpakning er at undgåoverflydende kolonnegrænsen, kan selv kode, der faktisk passer inden for kolonnegrænsen, måske linjeindpakket efter forfatterens skøn.

Tip: udpakning af en metode eller lokal variabel kan løse problemetuden behov for linjeindpakning.

4.5.1 hvor skal man bryde

hoveddirektivet for linjeindpakning er: foretrækker at bryde på ethøjere syntaktisk niveau. Også:

1. når en linje er brudt hos en ikke-tildelingsoperatør, kommer pausen foran symbolet. (Bemærk, at dette ikke er den samme praksis, der bruges i Google style til andre sprog, såsom C++ og JavaScript.)
   • dette gælder også for følgende “operatorlignende” symboler:
     • dot-separatoren (.)
     • de to koloner i en metodereference (::)
     • et ampersand i en type bundet (<T extends Foo & Bar>)
     • et rør i en fangstblok (catch (FooException | BarException e)).
2. når en linje brydes hos en tildelingsoperatør, kommer pausen typisk efter symbolet, men begge veje er acceptable.
   • dette gælder også for” assignment-operator-like”kolon i en forbedret for (“foreach”) erklæring.
3. en metode eller konstruktørnavn forbliver knyttet til den åbne parentes ((), der følger den.
4. et komma (,) forbliver knyttet til det token, der går forud for det.
5. en linje er aldrig brudt ved siden af pilen i en lambda, bortset fra at en pause kan komme umiddelbart efter pilen, hvis lambdaens krop består af et enkelt ubrac udtryk. Eksempler:

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

Bemærk: det primære mål for linjeindpakning er at have clearcode, ikke nødvendigvis kode, der passer ind i det mindste antal linjer.

4.5.2 indrykk fortsættelseslinjer mindst +4 mellemrum

Ved linjeindpakning er hver linje efter den første (hver fortsættelseslinje) indrykket mindst +4 fra den oprindelige linje.

når der er flere fortsættelseslinjer, kan indrykning varieres ud over +4 som ønsket. Generelt bruger to fortsættelseslinjer det samme indrykningsniveau, hvis og kun hvis debegynd med syntaktisk parallelle elementer.

afsnit 4.6.3 om horisontale justeringsadresserden modløse praksis med at bruge et variabelt antal mellemrum til at justere visse tokens med tidligere linjer.

4.6 mellemrum

4.6.1 lodret mellemrum

en enkelt tom linje vises altid:

1. mellem på hinanden følgende medlemmer eller initialisatorer af en klasse: felter, konstruktører, metoder, indlejrede klasser, statiske initialisatorer og instansinitialisatorer.
   • undtagelse: en tom linje mellem to på hinanden følgende felter (uden anden kode mellem dem) er valgfri. Sådanne tomme linjer bruges efter behov til at oprette logiske grupperinger af felter.
   • undtagelse: tomme linjer mellem enum-konstanter er dækket i afsnit 4.8.1.
2. som krævet i andre afsnit i dette dokument (såsom afsnit 3, Kildefilstruktur og afsnit 3.3, Importopgørelser).

en enkelt tom linje kan også vises hvor som helst det forbedrer læsbarheden, for eksempel mellemudsagn til at organisere koden i logiske underafsnit. En tom linje før det første medlem eller initialisator, eller efter det sidste medlem eller initialisator af klassen, er hverken opmuntret nordiscouraged.

flere på hinanden følgende tomme linjer er tilladt, men kræves aldrig (eller opmuntres).

4, 6.2 vandret mellemrum

ud over hvor det kræves af sproget eller andre stilregler, og bortset fra bogstaver, kommentarer ogjavadoc, vises et enkelt ASCII-rum kun på følgende steder.

1. adskillelse af ethvert reserveret ord, såsom iffor eller catch, fra en åben parentes ((), der følger det på den linje
2. adskillelse af ethvert reserveret ord, såsom else eller catch, fra en afsluttende krøllet bøjle (}), der går forud for den linje
3. før enhver åben krøllet bøjle ({), med to undtagelser:
   • @SomeAnnotation({a, b}) (der bruges ikke plads)
   • String x = {{"foo"}}; (der kræves ikke plads mellem {{, efter punkt 8 nedenfor)
4. på begge sider af enhver binær eller ternær operatør. Dette gælder også for følgende “operatørlignende” symboler:
   • ampersand i en konjunktiv type bundet: <T extends Foo & Bar>
   • røret til en fangstblok, der håndterer flere undtagelser: catch (FooException | BarException e)
   • tyktarmen (:) i en forbedretfor (“foreach”) erklæring
   • pilen i et lambda-udtryk: (String str) -> str.length()

   men ikke

   • de to koloner (::) af en metodehenvisning, som er skrevet som Object::toString
   • dot-separatoren (.), som er skrevet som object.toString()
5. efter ,:; eller den afsluttende parentes ()) af en rollebesætning
6. på begge sider af dobbelt skråstreg (//), der begynder en end-of-line kommentar. Her er flere mellemrum tilladt, men ikke påkrævet.
7. mellem typen og variablen af en erklæring: List<String> list
8. valgfri lige inden for begge seler af en array initialisator
   • new int {5, 6} og new int { 5, 6 } er begge gyldige
9. mellem en type annotation og eller ....

denne regel fortolkes aldrig som at kræve eller forbyde ekstra plads ved starten af en linje; den adresserer kun det indre rum.

4.6.3 vandret justering: aldrig påkrævet

terminologi Note: Vandret justering erpraksis med at tilføje et variabelt antal ekstra mellemrum i din kode med det formål at lavevisse tokens vises direkte under visse andre tokens på tidligere linjer.

denne praksis er tilladt, men kræves aldrig af Google Style. Det er ikkeselv nødvendigt at opretholde vandret justering på steder, hvor den allerede blev brugt.

Her er et eksempel uden justering, og brug derefter justering:

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

Tip: justering kan hjælpe læsbarheden, men det skaber problemer forfremtidig vedligeholdelse. Overvej en fremtidig ændring, der kun skal berøre en linje. Denne ændring kanForlad den tidligere behagelige formatering manglet, og det er tilladt. Oftere beder den koderen (måske dig) om også at justere mellemrum på nærliggende linjer, eventuelt at udløse en cascading række omformateringer. Denne enlinjeændring har nu en ” eksplosionsradius.”Dette kan i værste fald resultere i meningsløst travlt arbejde, men i bedste fald ødelægger det stadig versionshistorienoplysninger, bremser korrekturlæsere og forværrer fusionskonflikter.

4.7 gruppering parenteser: anbefalet

valgfri grupperingsparentes udelades kun, når forfatter og korrekturlæser er enige om, at der ikke er nogen rimelig chance for, at koden vil blive fortolket uden dem, og de ville heller ikke have gjort kodenlettere at læse. Det er ikke rimeligt at antage, at hver læser har hele Javaoperator-præcedensbordet gemt.

4.8 specifikke konstruktioner

4.8.1 enum-klasser

efter hvert komma, der følger en enum-konstant, er et linjeskift valgfrit. Yderligere blanklines (normalt kun en) er også tilladt. Dette er en mulighed:

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

en enum-klasse uden metoder og ingen dokumentation på dens konstanter kan eventuelt formatteres, hvis det var en array-initialisator (se Afsnit 4.8.3.1 onarray-initialisatorer).

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

da enum-klasser er klasser, gælder alle andre regler for formatering af klasser.

4.8.2 Variabeldeklarationer

4.8.2.1 en variabel pr.erklæring

hver variabeldeklaration (felt eller lokal) erklærer kun en variabel: erklæringer somint a, b; anvendes ikke.

undtagelse: Flere variable erklæringer er acceptable i overskriften på enfor loop.

4.8.2.2 deklareret efter behov

lokale variabler deklareres ikke sædvanligvis ved starten af deres indeslutningsblok eller bloklignende konstruktion. I stedet erklæres lokale variabler tæt på det punkt, de erførst brugt (inden for grund) for at minimere deres omfang. Lokale variable erklæringer har typiskinitialisatorer eller initialiseres umiddelbart efter erklæringen.

4.8.3 Arrays

4.8.3.1 array initialisatorer: kan være”bloklignende”

enhver array-initialisator kan eventuelt formateres som om det var en “bloklignende konstruktion.”For eksempel er følgende alle gyldige (ikke en udtømmende liste):

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 ingen C-style array-erklæringer

de firkantede parenteser udgør en del af typen, ikke variablen: String args, ikke String args.

4.8.4 skift udsagn

terminologi Bemærk: inde i seler af asafbryder blok er en eller flere udsagn grupper. Hver udsagnsgruppe består af en eller flere skifteetiketter (enten case FOO: ellerdefault:) efterfulgt af en eller flere udsagn (eller for den sidste udsagnsgruppe nul eller flere udsagn).

4.8.4.1 indrykning

som med enhver anden blok er indholdet af en omskifterblok indrykket +2.

efter en omskifteretiket er der en linjeskift, og indrykningsniveauet øges +2, nøjagtigtsom om en blok blev åbnet. Følgende skiftetiket vender tilbage til den forrige indentationniveau, som om en blok var blevet lukket.

4.8.4.2 Fall-through: kommenteret

inden for en omskifterblok afsluttes hver udsagnsgruppe enten brat (med enbreakcontinuereturn eller kastet undtagelse) eller er markeret med en kommentarfor at indikere, at udførelsen vil eller kan fortsætte i den næste udsagnsgruppe. Anycomment, der kommunikerer ideen om gennemfald, er tilstrækkelig (typisk// fall through). Denne særlige kommentar er ikke påkrævet iDen sidste udsagnsgruppe af omskifterblokken. Eksempel:

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

Bemærk, at der ikke er behov for nogen kommentar eftercase 1:, kuni slutningen af udsagnsgruppen.

4.8.4.3default sagen er til stede

hver skiftesætning indeholder endefault erklæringsgruppe, selvom den ikke indeholder nogen kode.

undtagelse: en skiftesætning for enenum type kan udeladedefault sætningsgruppe, hvis den inkluderereksplicitte tilfælde, der dækker alle mulige værdier af den type. Dette gør det muligt for IDE ‘ er eller andre staticanalyseværktøjer at udsende en advarsel, hvis nogen tilfælde blev savnet.

4.8.5 anmærkninger

anmærkninger, der gælder for en klasse, metode eller konstruktør, vises umiddelbart efterdokumentationsblok, og hver annotation er angivet på en egen linje (det vil sige en annotationper linje). Disse linjeskift udgør ikke linjeindpakning (Afsnit4.5, Linjeindpakning), så indrykningsniveauet er ikkeøget. Eksempel:

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

undtagelse: En enkelt parameterless annotationkan i stedet vises sammen med den første linje i signaturen, for eksempel:

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

annotationer, der gælder for et felt, vises også umiddelbart efter dokumentationsblokken, men idette tilfælde kan flere annotationer (muligvis parameteriseret) være angivet på samme linje;for eksempel:

@Partial @Mock DataLoader loader;

Der er flere ingen specifikke regler for formatering af anmærkninger på parametre, lokale variabler eller typer.

dette afsnit omhandler implementeringskommentarer. Javadoc adresseres separat isektion 7, Javadoc.

ethvert linjeskift kan indledes med vilkårlig mellemrum efterfulgt af en implementeringskommentar.En sådan kommentar gør linjen ikke tom.

4.8.6.1 blok kommentar stil

blok kommentarer er indrykket på samme niveau som den omgivende kode. De kan være i/* ... */style eller// ... style. For multi-line/* ... */kommentarer skal efterfølgende linjer starte med*justeret med* på den foregående linje.

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

kommentarer er ikke vedlagt i kasser tegnet med stjerner eller andre tegn.

Tip: når du skriver kommentarer med flere linjer, skal du bruge/* ... */ stil, hvis du vil have automatiske kodeformatører til at rive linjerne, når det er nødvendigt (afsnit-stil). De fleste formatere ombrydes ikke linjer i// ... stil kommentar blokke.

4.8.7 modifikatorer

klasse-og medlemsmodifikatorer vises, når de er til stede, i ordrenanbefalet af Java-Sprogspecifikationen:

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

4.8.8 numeriske bogstaver

long-værdsatte heltalslitteraler bruger et stort bogstavLsuffiks, aldriglavt (for at undgå forveksling med cifferet1). For eksempel 3000000000Lsnarere end 3000000000l.

5 navngivning

5.1 regler, der er fælles for alle identifikatorer

identifikatorer bruger kun ASCII-bogstaver og cifre og understreger i et lille antal tilfælde, der er nævnt nedenfor. Således matches hvert gyldigt identifikatornavn med det regulære udtryk\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.

klassenavne er typisk navneord eller navneordssætninger. For eksempelCharacterellerImmutableList. Interfacenavne kan også være navneord ellernoun sætninger (for eksempel List), men kan nogle gange væreadjektiver eller adjektiv sætninger i stedet (for eksempelReadable).

der er ingen specifikke regler eller endda veletablerede konventioner til navngivning af annotationstyper.

testklasser navngives startende med navnet på den klasse, de tester, og slutter medTest. For eksempelHashTest ellerHashIntegrationTest.

5.2.3 Metodenavne

Metodenavne er skrevet i småkamelcase.

Metodenavne er typisk verb eller verbsætninger. For eksempelsendMessage ellerstop.

understregninger kan forekomme i JUnit-testmetodenavne for at adskille logiske komponenter i det navn, hvor hver komponent er skrevet i småkamelcase.Et typisk mønster er <methodUnderTest>_<state>,for eksempel pop_emptyStack. Der er ingen Korrektmåde at navngive testmetoder på.

5. 2.4 konstante navne

konstante navne brugCONSTANT_CASE: alle store bogstaver, med hvert ord adskilt fra det næste med en enkelt understregning. Men hvad er aconstant, præcis?

konstanter er statiske endelige felter, hvis indhold er dybt uforanderlige, og hvis metoder har nodetekterbare bivirkninger. Dette inkluderer primitiver, strenge, uforanderlige typer og uforanderlige samlinger af uforanderlige typer. Hvis nogen af instansens observerbare tilstand kan ændre sig, er den ikke konstant. Det er ikke nok at have til hensigt aldrig at mutere objektet. Eksempel:

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

disse navne er typisk navneord eller navneordssætninger.

5.2.5 ikke-konstante feltnavne

ikke-konstante feltnavne (statiske eller på anden måde) er skreveti laverkamelcase.

disse navne er typisk navneord eller navneordssætninger. For eksempelcomputedValuesellerindex.

5.2.6 parameternavne

parameternavne er skrevet i småkamelcase.

parameternavne med et tegn i offentlige metoder bør undgås.

5.2.7 lokale variabelnavne

lokale variabelnavne er skrevet i småkamelcase.

selv når de er endelige og uforanderlige, anses lokale variabler ikke for at være konstanter og bør ikke Styles som konstanter.

5.2.8 type variabelnavne

hver type variabel er navngivet i en af to stilarter:

• et enkelt stort bogstav, eventuelt efterfulgt af et enkelt tal (såsomETXT2)
• et navn i den form, der bruges til klasser (se afsnit 5.2.2, klassenavne) efterfulgt af store bogstaverT (eksempler: RequestTFooBarT).

5.3 Camel case: defineret

Nogle gange er der mere end en rimelig måde at konvertere en engelsk sætning til camel case,som når akronymer eller usædvanlige konstruktioner som “IPv6” eller “iOS” er til stede. For at forbedreforudsigelighed specificerer Google Style følgende (næsten) deterministiske skema.

begyndende med prosaformen af navnet:

1. konverter sætningen til almindelig ASCII og fjern eventuelle apostrofer. For eksempel kan” m Larrller ‘ s algorithm “blive”Muellers algorithm”.
2. Opdel dette resultat i ord, opdeling på mellemrum og eventuel resterende tegnsætning (typisk bindestreger).
   • anbefalet: hvis et ord allerede har et konventionelt camel-case-udseende i almindelig brug, skal du opdele dette i dets bestanddele (f.eks. Bemærk, at et ord som “iOS” ikke rigtig er i camel-tilfælde i sig selv; det trodser enhver konvention, så denne anbefaling gælder ikke.
3. nu små bogstaver alt (herunder akronymer), så store bogstaver kun det første tegn på:
   • … hvert ord, for at give øvre kamel sag, eller
   • … hvert ord undtagen det første, for at give lavere kamel sag
4. endelig skal du slutte alle ordene til en enkelt identifikator.

Bemærk, at foringen af de originale ord næsten helt ses bort fra. Eksempel:

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: altid brugt

en metode er markeret med@Override annotationnår det er lovligt. Dette inkluderer en klassemetode, der tilsidesætter en superklassemetode, en klassemetodeimplementering af en grænseflademetode og en grænseflademetode, der respekterer en supergrænseflademetode.

undtagelse: @Overridekan udelades, når den overordnede metode er@Deprecated.

6.2 fangede undtagelser: ikke ignoreret

undtagen som nævnt nedenfor er det meget sjældent korrekt at gøre noget som svar på en fangetundtagelse. (Typiske svar er at logge det, eller hvis det betragtes som “umuligt”, skal du gentage det som etAssertionError.)

Når det virkelig er hensigtsmæssigt at tage nogen som helst handling i en fangstblok, forklares årsagen til, at dette er berettiget, 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);

undtagelse: i test kan en fanget undtagelse ignoreresuden kommentar, hvis navnet er eller begynder medexpected. Detfølgende er et meget almindeligt formsprog for at sikre, at koden under test kaster en undtagelse af den forventede type, så en kommentar er unødvendig her.

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

6.3 statiske medlemmer: kvalificeret ved hjælp af klasse

Når en henvisning til et statisk klassemedlem skal være kvalificeret, er det kvalificeret med det klassenavn, ikke med en reference eller et udtryk for den klasses type.

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

6.4 Finalisatorer: ikke brugt

det er ekstremt sjældent at tilsidesætteObject.finalize.

Tip: gør det ikke. Hvis du absolut skal, skal du først læse og forstå effektiv Java-punkt 7,”undgå Finalisatorer”, meget omhyggeligt, og så gør det ikke.

7 Javadoc

7.1 formatering

7.1.1 generel form

den grundlæggende formatering af Javadoc-blokke ses i dette eksempel:

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

… eller i dette enkeltlinjeeksempel:

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

grundformularen er altid acceptabel. Enkeltlinjeformularen kan erstattes, når hele Javadoc-blokken (inklusive kommentarmarkører) kan passe på en enkelt linje. Bemærk, at dette kun gælder, når der ikke er nogen blokmærker som @return.

7. 1.2 Afsnit

en tom linje—det vil sige en linje, der kun indeholder den justerede førende stjerne(*)—vises mellem afsnit og før gruppen af blokmærker, hvistil stede. Hvert afsnit, men det første har <p> umiddelbart før det første ord,uden plads efter.

7.1.3 Block tags

enhver af de standard “block tags”, der bruges, vises i rækkefølgen@param@return@throws@deprecated, og disse fire typer aldrigvises med en tom beskrivelse. Når et blokmærke ikke passer på en enkelt linje, fortsættelseslinjerer indrykket fire (eller flere) mellemrum fra placeringen af @.

7.2 sammendragsfragmentet

hver Javadoc-blok begynder med et kort sammendragsfragment. Dettefragment er meget vigtigt: det er den eneste del af teksten, der vises i visse sammenhænge som f.eksklasse-og metodeindekser.

dette er et fragment-en substantiv sætning eller verb sætning, ikke en komplet sætning. Det begynder ikke med A {@code Foo} is a..., ellerThis method returns..., og det danner heller ikke en komplet imperativ sentencelike Save the record.. Fragmentet er dog aktiveret ogpunkteret som om det var en komplet sætning.

Tip: en almindelig fejl er at skrive simpel Javadoc i formularen/** @return the customer ID */. Dette er forkert, og bør væreændret til /** Returns the customer ID. */.

7.3 Hvor Javadoc anvendes

som minimum, er Javadoc til stede for hverpublic klasse, og hvertpublic ellerprotected medlem af en sådan klasse, med nogle få undtagelserbemærket nedenfor.

yderligere Javadoc-indhold kan også være til stede, som forklaret i afsnit 7.3.4,ikke-påkrævet Javadoc.

7.3.1 undtagelse: selvforklarende metoder

Javadoc er valgfri for “enkle, indlysende” metoder somgetFoo, i tilfælde hvor der virkelig og virkelig erintet andet værd at sige, men “returnerer foo”.

vigtigt: det er ikke hensigtsmæssigt at citere denne undtagelse for at begrunde, at der gives relevante oplysninger, som en typisk læser muligvis har brug for at vide. For eksempel for en metodenavnet getCanonicalName, udelad ikke dens dokumentation(med begrundelsen for, at den kun ville sige/** Returns the canonical name. */), hvis en typisk læser muligvis ikke har nogen idehvad udtrykket “kanonisk navn” betyder!

7.3.2 undtagelse: tilsidesætter

Javadoc er ikke altid til stede på en metode, der tilsidesætter en supertype-metode.

7.3.4 ikke-påkrævet Javadoc

andre klasser og medlemmer har Javadoc efter behov eller ønsket.