1 Johdanto

Tämä asiakirja toimii Googlen koodausstandardien täydellisenä määritelmänä Java™ – ohjelmointikielen koodaukselle. Java-lähdekooditiedosto on kuvattu inGoogle-tyyliseksi, jos ja vain jos se noudattaa tässä olevia sääntöjä.

kuten muutkin ohjelmointityylioppaat, käsiteltävät asiat eivät koske pelkästään esteettisiä formaattiin liittyviä kysymyksiä, vaan myös muunlaisia konventioita tai koodausstandardeja. Tässä dokumentissa keskitytään kuitenkin ensisijaisesti koviin ja nopeisiin sääntöihin, joita noudatamme yleisesti, ja annetaan neuvoja, jotka eivät ole selvästi täytäntöönpanokelpoisia (joko ihmisen tai työkalun avulla).

1.1 terminologia toteaa

tässä asiakirjassa, ellei toisin selvennetä:

1. termiluokkaa käytetään myös tarkoittamaan ”tavallista” luokkaa, enum-luokkaa, liittymää tai huomautustyyppiä (@interface).
2. termillä (luokan jäsen) tarkoitetaan sisäkkäistä luokkaa, kenttää, menetelmää tai konstruktoria; eli kaikki luokan ylätason sisältö paitsi alustajat ja kommentit.
3. termikommentilla tarkoitetaan aina toteutuskommentteja. Emme käytä ilmaisua ”dokumentaatiokommentit”, vaan yleistä termiä ” Javadoc.”

muita” terminologiahuomautuksia ” ilmestyy satunnaisesti koko dokumentissa.

1.2 Ohjehuomautukset

tämän asiakirjan esimerkkikoodi on normatiivinen. Toisin sanoen, vaikka esimerkit ovat Googlen tyyliin, ne eivät välttämättä kuvaa ainoa tyylikäs tapa edustaa thecode. Esimerkeissä tehtyjä valinnaisia muotoiluvalintoja ei pidä panna täytäntöön sääntöinä.

2 lähdetiedoston perusteet

2.1 tiedostonimi

lähdetiedoston nimi koostuu sen sisältämän ylätason(josta on tasan yksi) kirjainlyhenteisestä nimestä sekä.java-laajennuksesta.

2.2 Tiedostokoodaus: UTF-8

lähdetiedostot koodataan UTF-8: aan.

2.3 erikoismerkit

2.3.1 Välilyöntimerkit

rivin terminaattorisarjan lisäksi ASCII: n horisontaalinen välilyöntimerkki (0x20) on ainoa välilyöntimerkki, joka esiintyy missä tahansa lähdetiedostossa. Tämä tarkoittaa, että:

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

2.3.3 muut kuin ASCII-merkit

jäljelle jäävissä ei-ASCII-merkeissä käytetään joko varsinaista Unicode-merkkiä(esimerkiksi ∞) tai vastaavaa Unicode-pakotietä(esimerkiksi \u221e). Valinta riippuu vain siitä, mikä helpottaa koodin lukemista ja ymmärtämistä, vaikka Unicode escapesoutside string literals ja kommentit ovat voimakkaasti lannistettuja.

Vihje: Unicode-pakojutussa ja toisinaan jopa aktuaalisten unicode-merkkien käytössä selittävä kommentti voi olla hyvin hyödyllinen.

esimerkkejä:

String unitAbbrev = "μs";

esimerkki	Keskustelu
paras: täysin selkeä jopa ilman kommenttia.
String unitAbbrev = "\u03bcs"; // "μs"	sallitaan, mutta siihen ei ole syytä.
String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"	sallittu, mutta hankala ja altis virheille.
String unitAbbrev = "\u03bcs";	huono: lukijalla ei ole aavistustakaan, mistä on kyse.
return '\ufeff' + content; // byte order mark	hyvä: käytä pakokeinoja ei-tulostettaville merkeille ja kommentoi tarvittaessa.

vihje: älä koskaan tee koodistasi vähemmän luettavaa vain pelosta, että jotkin ohjelmat eivät ehkä käsittele muita kuin ASCII-merkkejä oikein. Jos näin tapahtuu, ohjelmat on rikottu ja ne on korjattava.

3 Lähdekooditiedostorakenne

tasan yksi tyhjä rivi erottaa jokaisen paikalla olevan osan.

3.1 Lisenssi-tai tekijänoikeustiedot, jos niitä on

Jos lisenssi-tai tekijänoikeustiedot kuuluvat tiedostoon, ne kuuluvat tänne.

3, 2 Pakkauslauseke

pakkauslauseke ei ole riviin kääritty. Sarakerajaa (kohta 4.4,sarakkeen yläraja: 100) ei sovelleta pakettilausekkeisiin.

3.3 Tuontilauseet

3.3.1 jokerimerkkien tuontia

staattista tai muuta ei käytetä.

3.3.2 ei riviin käärittyjä

Tuontilausekkeita ei ole riviin käärittyjä. Sarakkeen raja-arvoa (4.4 kohdan sarakkeen raja-arvo: 100) ei sovelleta tuontitavaroihin.

3.3.3 järjestys ja väli

tuonti on järjestetty seuraavasti:

1. kaikki staattinen tuonti yhtenä lohkona.
2. kaikki ei-staattiset tuonnit yhdessä lohkossa.

Jos on sekä staattista että ei-staattista tuontia, yksi tyhjä rivi erottaa twoblockit. Ei ole muita tyhjiä rivejä tuontilauseiden välillä.

kussakin lohkossa tuodut nimet esiintyvät ASCII-lajittelujärjestyksessä. (Huomautus: Tämä ei ole sama kuin tuo lausekkeet ovat ASCII lajittelujärjestyksessä, koska ”.”lajittelee ennen”;”.)

3.3.4 luokille

staattista tuontia ei käytetä staattisissa sisäkkäisissä luokissa. Ne tuodaan tavanomaisella tuonnilla.

3.4 Luokkailmoitus

3.4.1 täsmälleen yksi ylätason luokkailmoitus

jokainen ylätason Luokka sijaitsee omassa lähdekooditiedostossaan.

3, 4.2 luokkasisällön tilaaminen

luokkasi jäsenille ja alustajille valitsemallasi järjestyksellä voi olla suuri vaikutus oppimiskykyyn. Yhtä oikeaa reseptiä sen tekemiseen ei kuitenkaan ole, vaan eri luokat voivat järjestää sisältönsä eri tavoin.

tärkeää on, että jokainen luokka käyttää jotakin loogista järjestystä, jonka sen ylläpitäjä voisi selittää, jos sitä kysyttäisiin. Esimerkiksi uusia menetelmiä ei vain tavallisesti lisätä luokan loppuun, koska se tuottaisi ”kronologisen päivämäärän mukaan lisätyn” tilauksen, joka ei ole loginen järjestys.

3.4.2.1 ylikuormitus: ei koskaan jaeta

kun luokalla on useita konstruktioita tai useita menetelmiä, joilla on sama nimi, nämä esiintyvät yhtäläisesti, eikä välissä ole muita koodeja (ei edes yksityisiä jäseniä).

4 formatointi

terminologia Huomautus: lohkomainen konstruktio viittaa luokan, menetelmän tai Konstruktion runkoon. Huomaa, että kohdassa 4.8.3.1 onarray initializers, kaikki array initializermay vaihtoehtoisesti käsitellään ikään kuin se olisi lohkon kaltainen konstruktio.

4, 1 henkselit

4, 1.1 henkseleitä käytetään, jos valinnaisia

henkseleitä käytetäänifelsefordo jawhile väittämät, vaikka thebody on tyhjä tai sisältää vain yhden lausekkeen.

4.1.2 Nonempty blocks: k & R-tyyli

henkselit noudattavat Kernighan-ja Ritchie-tyyliä(”egyptiläiset sulut”)nonempty blocks and block-like constructions:

• no line break before the opening brace.
• linja katkesi avauspuoliajan jälkeen.
• linja katkesi ennen päätössuoritusta.
• viiva katkeaa sulkusuojan jälkeen vain, jos kyseinen ahdin päättää lausekkeen tai päättää metodin, rakentajan tai nimetyn luokan kappaleen. Esimerkiksi ahdin jälkeen ei ole viivamurtumaa, jos sitä seuraa else tai pilkku.

esimerkkejä:

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

muutamia poikkeuksia enum-luokista on esitetty kohdassa 4.8.1,Enum-luokat.

4.1.3 tyhjät lohkot: voi olla tiivis

tyhjä lohko tai lohkomainen konstruktio voi olla k & R-tyylinen (kuvatulla insektiolla 4.1.2). Vaihtoehtoisesti se voidaan sulkea välittömästi sen avaamisen jälkeen, jolloin välissä ei ole merkkejä tai rivinvaihdetta({}), ellei se ole osa monilukuista lauseketta (joka sisältää suoraan useita lohkoja:if/else taitry/catch/finally).

Examples:

 // 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 lohkon sisennys: +2 välilyöntiä

aina kun uusi lohko tai lohkomainen konstruktio avataan, sisennys kasvaa kahdella välilyönnillä. Kun lohko päättyy, sisennys palaa edelliselle sisennystasolle. Luetelmakohtaa sovelletaan sekä koodiin että huomautuksiin koko kentässä. (Katso esimerkki kohdassa 4.1.2, Nonempty blocks: k & R Style.)

4.3 yksi lauseke per rivi

jokaista lausetta seuraa rivimurto.

4,4 sarakkeen raja: 100

Java-koodin sarakeraja on 100 merkkiä. ”Merkillä” tarkoitetaan mitä tahansa Unicode-koodipistettä.Lukuun ottamatta jäljempänä mainittua, kaikki viivat, jotka ylittävät tämän rajan, on käärittävä riviin, kuten selitettiin inSection 4.5, Line-wraping.

jokainen Unicode-koodin piste lasketaan yhdeksi merkiksi, vaikka sen näytön leveys olisi suurempi tai pienempi. Esimerkiksi, jos usingfullwidth merkkejä, voit päättää kääri rivi aikaisemmin kuin jos tämä sääntö tiukasti edellyttää.

poikkeukset:

1. rivit, joilla sarakerajan noudattaminen ei ole mahdollista (esimerkiksi pitkä URL javadocissa tai pitkä jsni-metodin viite).
2. package ja import lausumat (katso kohdat 3.2 Pakettilausunto ja 3.3 Tuontilausunto).
3. komentorivit kommentissa, joka voidaan leikata ja liittää komentotulkkiin.

4.5 rivien kääriminen

terminologia Huomautus: Kun koodi, joka muuten saattaisi merkitä yhtä riviä, jaetaan useaksi riviksi, tätä toimintoa kutsutaan rivien käärimiseksi.

ei ole olemassa kattavaa, determinististä kaavaa, joka osoittaisi tarkalleen, miten rivinveto tehdään jokaisessa tilanteessa. Hyvin usein on olemassa useita päteviä tapoja rivittää sama koodi.

huomautus: Vaikka tyypillinen syy rivien käärimiseen on sarakerajan ylittämisen välttäminen, jopa koodi, joka itse asiassa sopisi sarakerajaan, saattaa olla riviin kääritty kirjoittajan harkinnan mukaan.

Vihje: menetelmän tai paikallisen muuttujan uuttaminen voi ratkaista ongelman ilman rivikäärimistä.

4.5.1 missä rikotaan

viivan käärimisen ensisijainen ohje on: mieluummin rikotaan korkeammalla syntaktisella tasolla. Myös:

1. kun linja katkeaa toimimattomalla operaattorilla, katkos tulee ennen tunnusta. (Huomaa, että tämä ei ole sama käytäntö kuin Google style muille kielille, kuten C++: lle ja JavaScriptille.)
   • tämä koskee myös seuraavia ”operaattorimaisia” tunnuksia:
     • pistenerotin (.)
     • metodiviittauksen kaksi pylvästä (::)
     • ampeerin tyyppi sidottuna (<T extends Foo & Bar>)
     • piippu saalislohkossa (catch (FooException | BarException e)).
2. kun viiva katkeaa tehtäväoperaattorissa, katkos tulee tyypillisesti symbolin jälkeen, mutta kumpi tahansa tapa on hyväksyttävä.
   • tämä koskee myös” assignment-operator-like ”- kaksoispistettä tehostetussa for (”foreach”) lauseessa.
3. sitä seuraavaan avoimeen suluun (() jää metodin tai rakentajan nimi.
4. pilkku (,) pysyy kiinni sitä edeltävässä tokenissa.
5. lambdassa ei koskaan rikota nuolen vieressä olevaa viivaa, paitsi että katkos voi tulla heti nuolen jälkeen, jos Lambdan runko koostuu yhdestä yhdistämättömästä lausekkeesta. Esimerkkejä:

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

Huom: rivien käärinnän ensisijainen tavoite on saada clearcode, ei välttämättä koodi, joka sopii pienimmälle rivimäärälle.

4.5.2 sisennä jatkolinjat vähintään +4 välilyöntiä

kun rivitys tehdään, jokainen ensimmäisen rivin jälkeinen rivi (jokainen jatkolinja) sisennetään vähintään +4 alkuperäisestä rivistä.

kun jatkorivejä on useita, sisennys voi vaihdella yli +4 asdesiredin. Yleensä kaksi jatkojanaa käyttävät samaa sisennystasoa, jos ja vain jos theybegin syntaktisesti yhdensuuntaisilla alkuaineilla.

horisontaalista linjausta koskevassa 4.6.3 kohdassa käsitellään kielteistä käytäntöä käyttää vaihtelevaa välilyöntimäärää tiettyjen sanakkeiden yhdenmukaistamiseksi aikaisempien rivien kanssa.

4. 6 välilyöntiä

4. 6. 1 pystysuuntainen Välilyöntitila

yksi tyhjä rivi näkyy aina:

1. peräkkäisten jäsenten tai luokan alustajien välillä: kentät, rakentajat, menetelmät, sisäkkäisiä luokkia, staattinen initializers, ja esimerkiksi initializers.
   • poikkeus: kahden peräkkäisen kentän välinen tyhjä rivi (jonka välissä ei ole muuta koodia) on valinnainen. Tällaisia tyhjiä rivejä käytetään tarpeen mukaan loogisten kenttien ryhmittelyjen luomiseen.
   • poikkeus: enumvakioiden välisiä tyhjiä viivoja käsitellään kohdassa 4.8.1.
2. kuten tämän asiakirjan muissa osissa vaaditaan (kuten kohdassa 3, lähdetiedoston rakenne, ja kohdassa 3.3, Tuontilauseet).

yksittäinen tyhjä rivi voi esiintyä myös missä tahansa, missä se parantaa luettavuutta, esimerkiksi tekstien välillä järjestäen koodin loogisiin alaluokkiin. Tyhjällä rivillä ennen ensimmäistä jäsentä tai aloittajaa tai luokan viimeisen jäsenen tai aloittajan jälkeen ei myöskään rohkaista nordiscouragea.

useita peräkkäisiä tyhjiä rivejä sallitaan, mutta niitä ei koskaan vaadita (tai kannusteta).

4, 6.2 vaakasuoraa välilyöntiä

yli, jos kieli tai muut tyylisäännöt sitä edellyttävät, ja literals -, comments andjavadocin lisäksi yksi ASCII-välilyönti näkyy myös vain seuraavissa kohdissa.

1. erottaa minkä tahansa varatun sanan, kuten iffor tai catch, avoimesta sulusta ((), joka seuraa sitä kyseisellä rivillä li>
2. erottaa minkä tahansa varatun sanan, kuten elsetai catch, sulkeutuvasta kiharatukasta (}), joka edeltää sitä kyseisellä linjalla
3. ennen mitään avointa kiharatukkaa ({) kahta poikkeusta lukuun ottamatta:
   • @SomeAnnotation({a, b}) (välilyöntiä ei käytetä)
   • String x = {{"foo"}}; (välilyöntiä ei tarvita {{, kohta 8 alla)
4. jokaisen binäärioperaattorin tai ternäärioperaattorin molemmin puolin. Tämä koskee myös seuraavia ”operaattorimaisia” tunnuksia:
   • ampersand konjunktiivisessa tyypissä sidottu: <T extends Foo & Bar>
   • useita poikkeuksia käsittelevän saalislohkon putki: catch (FooException | BarException e)
   • kaksoispiste (:) tehostetussa for (”foreach”) lauseessa
   • nuoli Lambdan lausekkeessa: (String str) -> str.length()

   mutta ei

   • metodiviittauksen kaksi kolonia (::), joka on kirjoitettu kuten Object::toString
   • pisteserotin (.), joka kirjoitetaan kuten object.toString()
5. jälkeen,:;tai sulkeva sulkeuma ()), joka on valettu
6. molemmin puolin kaksoisviiva (//), joka aloittaa rivien loppukommentin. Täällä useita tiloja sallitaan, mutta ei vaadita.
7. julistuksen tyypin ja muuttujan välillä: List<String> list
8. valinnainen vain array-alustajan molempien aaltosulkujen sisällä
   • new int {5, 6} ja new int { 5, 6 } ovat molemmat voimassa
9. välillä tyyppimerkintä ja tai ....

tätä sääntöä ei koskaan tulkita niin, että se vaatisi tai kieltäisi lisätilaa jonon alkupäässä, vaan se koskee vain sisätiloja.

4.6.3 horisontaalinen linjaus: ei koskaan vaadittu

terminologia Huomautus: Horisontaalinen kohdistus on käytäntö, jossa lisätään muuttuva määrä ylimääräisiä välilyöntejä koodiin tavoitteena saada tietyt poletit näkyvät suoraan tiettyjen muiden polettien alapuolella edellisillä riveillä.

Tämä käytäntö on sallittu, mutta Google Style ei sitä koskaan vaadi. Sitä ei edes vaadita säilyttämään vaakasuora kohdistus paikoissa, joissa se oli jo käytetty.

tässä on esimerkki ilman linjausta, sitten käyttäen linjausta:

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

Tip: linjaus voi auttaa luettavuutta, mutta se aiheuttaa ongelmia tulevaisuuden kunnossapidolle. Mieti tulevaa muutosta, jonka on koskettava vain yhtä viivaa. Tämä muutos saattaa jättää aiemmin miellyttäneen muotoilun mankeloiduksi, ja se on sallittua. Useammin se kehottaa koodaajaa (ehkä sinua) säätämään välilyönnit myös lähiriveillä, mikä mahdollistaa ryöppyävän sarjan muokkauksia. Tuo yhden linjan muutos on nyt ” räjähdyssäde.”Tämä voi pahimmillaan johtaa turhiin puuhasteluihin, mutta parhaimmillaan se silti turmelee versiohistoriallisia tietoja, hidastaa arvostelijoita ja pahentaa yhdistymisristiriitoja.

4. 7 sulkeiden ryhmittely: suositellut

vapaaehtoiset ryhmittelysulkeet jätetään pois vain silloin, kun laatija ja arvioija ovat yhtä mieltä siitä, että koodia ei voida tulkita väärin ilman niitä, eivätkä ne olisi saaneet koodia lukemaan. Ei ole järkevää olettaa, että jokaisella lukijalla on koko Javaoperator-ennakkotaulukko ulkoa.

4.8 spesifiset konstruktiot

4.8.1 Enumluokat

jokaisen enumvakiota seuraavan pilkun jälkeen rivimurto on valinnainen. Myös ylimääräisiä tyhjiä rivejä (yleensä vain yksi) sallitaan. Tämä on yksi mahdollisuus:

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

enum-luokka, jolla ei ole menetelmiä eikä dokumentaatiota sen vakioista, voidaan vaihtoehtoisesti muodostaa, jos se olisi matriisin initializer (KS.kohta 4.8.3.1 onarray initializers).

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

koska enum-luokat ovat luokkia, sovelletaan kaikkia muita muotoiluluokkien sääntöjä.

4.8.2 muuttuja-ilmoitukset

4.8.2.1 yksi muuttuja per ilmoitus

jokainen muuttuja-ilmoitus (kenttä-tai paikallinen) ilmoittaa vain yhden muuttujan: sellaisia ilmoituksia kuinint a, b; ei käytetä.

poikkeus: Useita muuttuvia ilmoituksia voidaan hyväksyä otsikonfor silmukka.

4.8.2.2 ilmoitetaan tarvittaessa

paikallisia muuttujia ei yleensä ilmoiteta niiden sisältävän lohkomaisen rakenteen alussa. Sen sijaan paikalliset muuttujat ilmoitetaan lähellä sitä pistettä, jota niitä käytetään (järjen puitteissa), jotta niiden soveltamisala olisi mahdollisimman pieni. Paikallismuuttujien ilmoituksissa on tyypillisesti alkuunpanijoita tai ne alustetaan heti ilmoituksen jälkeen.

4.8.3 ryhmät

4.8.3.1 ryhmien alustajat: voi olla”lohkomainen”

mikä tahansa matriisin alustaja voidaan vaihtoehtoisesti muotoilla ikään kuin se olisi ”lohkomainen konstruktio.”Esimerkiksi seuraavat ovat kaikki kelvollisia (ei tyhjentävä luettelo):

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 ei C-tyylisiä taulukkoilmoituksia

hakasulkeet ovat osa tyyppiä, eivät muuttujaa:String args, eiString argsString argsString args.

4.8.4 Kytkinlauseet

terminologia Huomautus: aswitch-lohkon henkselien sisällä on yksi tai useampi lauseryhmä. Jokainen lausekeryhmä koostuu yhdestä tai useammasta vaihteen etiketistä (joko case FOO: taidefault:), jota seuraa yksi tai useampi lauseke (tai viimeisen lausekeryhmän osalta nolla tai useampi lauseke).

4.8.4.1 sisennys

kuten minkä tahansa muun lohkon kohdalla, kytkinlohkon sisältö sisennetään +2.

Kytkimen etiketin jälkeen on viivamurtuma, ja sisennystasoa nostetaan +2, tarkalleen ottaen, jos lohko avattaisiin. Seuraava Kytkimen merkki palaa edelliselle sisennystasolle, ikään kuin lohko olisi suljettu.

4.8.4.2 kaatuminen: kommentoi

kytkinlohkon sisällä jokainen lauseryhmä joko päättyy äkillisesti (breakcontinuereturn tai heitetään poikkeus), tai on merkitty kommentilla, joka osoittaa, että toteutus jatkuu tai saattaa jatkua seuraavaan lauseryhmään. Mikä tahansa putoamisajatuksesta viestivä komentti on riittävä (tyypillisesti// fall through). Tätä erityishuomautusta ei vaadita vaihtolohkon viimeisessä lauseryhmässä. Esimerkiksi:

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

huomaa, ettei kommenttia tarvita case 1: jälkeen, vain lausuntoryhmän lopussa.

4.8.4.3 default tapaus on läsnä

jokainen kytkinlauseke sisältää default statementgroup, vaikka se ei sisältäisi koodia.

poikkeus: enum type voi jättää pois default statement group, jos se sisältää eksplicit-tapaukset, jotka kattavat kaikki mahdolliset kyseisen tyypin arvot. Näin IDEs tai muut staticanalysis työkalut voivat antaa varoituksen, jos jokin tapaus jäi huomaamatta.

4.8.5 Huomautus

luokkaan, menetelmään tai konstruktoriin sovellettavat huomautukset ilmestyvät heti paperilohkon jälkeen, ja jokainen huomautus on lueteltu omalla rivillään (eli yhdellä merkinnällä per rivi). Nämä viivatauot eivät muodosta viivan käärimistä (osa 4.5, viivan käärimistä), joten sisennystaso ei kasva. Esimerkki:

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

poikkeus: Yksittäinen parametriton huomautus voi sen sijaan esiintyä yhdessä allekirjoituksen ensimmäisen rivin kanssa, esimerkiksi:

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

kenttää koskevat merkinnät näkyvät myös heti dokumentointilohkon jälkeen, mutta tässä tapauksessa useita (mahdollisesti parametrisoituja) merkintöjä voidaan luetella samalla rivillä;esimerkiksi:

@Partial @Mock DataLoader loader;

ei ole erityisiä sääntöjä parametrien, paikallisten muuttujien tai tyyppien merkintöjen muotoiluun.

tässä jaksossa käsitellään täytäntöönpanoa koskevia huomautuksia. Javadocia käsitellään erikseen insektio 7, Javadoc.

rivin katkeamista voi edeltää mielivaltainen tyhjämerkki, jota seuraa toteutuskommentti.Tällainen kommentti tekee rivistä tyhjän.

4.8.6.1 Lohkokommenttityyli

Lohkokommentit sisennetään samalla tasolla kuin ympäröivä koodi. Ne voivat olla /* ... */ style tai// ... style. Multi-line/* ... */ Kommentit, seuraavat rivit on aloitettava* linjassa * edellisen rivin kanssa.

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

kommentteja ei ole liitetty tähdellä tai muilla merkeillä piirrettyihin ruutuihin.

Vihje: kirjoittaessasi monirivisiä kommentteja, käytä/* ... */ style, jos haluat automaattisia koodiformaatteja repimään rivejä tarvittaessa (kappaletyyli). Suurin osa formaateista ei kääri rivejä uudelleen// ... style comment blocks.

4.8.7 modifioijat

luokka-ja jäsenmuunnokset esiintyvät Java-Kielimäärittelyn suosittelemassa järjestyksessä:

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

4.8.8 numeeriset Literaalit

long-arvoiset kokonaislukulukuluvut käyttävät isoja kirjaimia L loppulukulukuja, neverlow-kirjaimia (jotta vältetään sekaannus numeron 1kanssa). Esimerkiksi 3000000000Leikä 3000000000l.

5 nimeäminen

5.1 kaikille tunnisteille yhteiset säännöt

tunnisteissa käytetään vain ASCII-kirjaimia ja-numeroita sekä muutamissa jäljempänä mainituissa tapauksissa alaviivoja. Näin jokaista kelvollista tunnistenimeä vastaa säännöllinen lauseke\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.

Luokkanimet ovat tyypillisesti substantiiveja tai substantiivilausekkeita. EsimerkiksiCharacter taiImmutableList. Liittymänimet voivat olla myös substantiiveja tai adjektiiveja (esimerkiksi List), mutta voivat joskus olla adjektiiveja tai adjektiiveja (esimerkiksiReadable).

merkintätyyppien nimeämiseen ei ole erityisiä sääntöjä tai edes vakiintuneita käytäntöjä.

Testiluokat nimetään alkaen testattavan luokan nimestä ja päättyen Test. EsimerkiksiHashTest taiHashIntegrationTest.

5.2.3 menetelmien nimet

menetelmien nimet kirjoitetaan pienaakkosiin.

Metodin nimet ovat tyypillisesti verbejä tai verbilausekkeita. EsimerkiksisendMessage taistop.

alaviivoja voi esiintyä JUnit-testimenetelmän nimissä erottamaan loogisia thenamen komponentteja siten, että jokainen komponentti on kirjoitettu lowercamelcaseen.Yksi tyypillinen kuvio on <methodUnderTest>_<state>,esimerkiksi pop_emptyStack. Ei ole olemassa ketään oikeaa tapaa nimetä testimenetelmiä.

5, 2.4 Vakionimet

Vakionimet käyttävät CONSTANT_CASE: kaikki uppokirjakkeet siten, että jokainen sana erotetaan seuraavasta yhdellä alaviivalla. Mutta mikä on aconstant, tarkalleen?

vakiot ovat staattisia loppukenttiä, joiden sisältö on syvästi muuttumaton ja joiden menetelmillä ei ole havaittavia sivuvaikutuksia. Tämä sisältää primitives, Jouset, muuttumaton tyypit, ja muuttumaton collections muuttumaton tyypit. Jos jokin ilmentymän havaittava tila voi muuttua, se ei ole akonstantti. Pelkkä aikomus olla koskaan muuttamatta kohdetta ei riitä. Esimerkiksi:

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

nämä nimet ovat tyypillisesti substantiiveja tai substantiivilausekkeita.

5.2.5 Ei-vakiokenttänimet

Ei-vakiokenttänimet (staattiset tai muut) on kirjoitettu lowercamelcaseen.

nämä nimet ovat tyypillisesti substantiiveja tai substantiivilausekkeita. EsimerkiksicomputedValues taiindex.

5.2.6 Parametrinimet

Parametrinimet kirjoitetaan lowercamelcaseen.

Yksimerkkisiä parametrinimiä julkisissa menetelmissä tulee välttää.

5.2.7 Paikallismuuttujan nimet

paikallismuuttujan nimet kirjoitetaan pienaakkosena.

lopullisia ja muuttumattomia paikallisia muuttujia ei pidetä vakioina, eikä niitä pidä luokitella vakioiksi.

5.2.8 Tyyppimuuttujan nimi

jokainen tyyppimuuttuja on nimetty jommallakummalla kahdella tyylillä:

• yhdellä isolla kirjaimella, valinnaisesti yhdellä numerolla (kuten ETXT2)
• luokista käytetty nimi (KS. kohta 5.2.2, luokkanimet), jota seuraa iso kirjain T (esimerkkejä: RequestTFooBarT).

5.3 Camel case: määritelty

joskus on olemassa useampi kuin yksi järkevä tapa muuntaa englanninkielinen lause kamelin tapaukseksi,kuten silloin, kun esiintyy lyhenteitä tai epätavallisia konstruktioita kuten ”IPv6” tai ”iOS”. Ennustettavuuden parantamiseksi Google Style määrittelee seuraavan (lähes) deterministisen järjestelmän.

nimen proosamuodosta alkava:

1. Muunna lause pelkäksi ASCII: ksi ja poista mahdolliset heittomerkit. Esimerkiksi ” Müllerin algoritmista ”saattaa tulla”Muellersin algoritmi”.
2. Jaa tämä tulos sanoihin, jakoväleihin ja jäljellä oleviin välimerkkeihin (tyypillisesti väliviivat).
   • suositus: jos jollakin sanalla on jo tavanomaisessa käytössä tavanomainen kamelikantainen ulkomuoto, Jaa tämä sen rakenneosiin (esimerkiksi ”AdWords” muuttuu ”ad-sanaksi”). Huomaa, että sana, kuten ”iOS”, ei oikeastaan ole Camelin tapauksessa sinänsä; se uhmaa mitään yleissopimusta, joten tämä suositus ei päde.
3. nyt pienaakkosilla kaikki (myös lyhenteet), sitten isoilla kirjaimilla vain:
   • ensimmäinen merkki… jokainen sana, antaa ylä-kamelin tapauksessa, tai
   • … jokainen sana paitsi ensimmäinen, tuottaa alemman kamelin tapauksessa
4. lopuksi yhdistää kaikki sanat yhdeksi tunnisteeksi.

huomaa, että alkuperäisten sanojen kotelo jätetään lähes kokonaan huomiotta. Esimerkiksi:

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: aina käytetty

menetelmä merkitään @Override merkinnällä aina, kun se on laillinen. Tämä sisältää luokkamenetelmän, joka ohittaa superluokan menetelmän, luokkamenetelmän, jolla toteutetaan rajapintamenetelmä, ja rajapintamenetelmän, joka vastaa superinterfacemethodia.

poikkeus:@Override voidaan jättää pois, kun kantamenetelmä on@Deprecated.

6.2 pyydetyt poikkeukset: ei ole huomioitu

, ellei alla ole mainittu, on hyvin harvoin oikein olla tekemättä mitään varoituksen vuoksi. (Tyypillisiä vastauksia ovat sen kirjaaminen, tai jos sitä pidetään ”mahdottomana”, rethrow it asAssertionError.)

kun on todella tarkoituksenmukaista olla ryhtymättä minkäänlaisiin toimiin saalislohkossa, syy tähän on selitetty kommentissa.

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

poikkeus: kokeissa pyydetty poikkeus voidaan jättää huomioimatta, jos sen nimi on tai alkaa kirjaimella expected. Thefollowing on hyvin yleinen idiomi, jolla varmistetaan, että testattavana oleva koodi ei heittele odotettua tyyppiä, joten kommentti on tarpeeton tässä.

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

6.3 staattiset jäsenet: hyväksytty käyttäen luokkaa

kun viittaus staattiseen luokan jäseneen on hyväksyttävä, se hyväksytään kyseisen luokan nimellä, ei viittauksella tai lausekkeella kyseisen luokan tyypistä.

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

6,4 Finalizers: ei käytössä

on äärimmäisen harvinaista ohittaa Object.finalize.

vinkki: Älä tee sitä. Jos ehdottomasti täytyy, ensin lukea ja ymmärtää tehokas Java kohta 7, ”Vältä Finalizers,” hyvin huolellisesti, ja sitten älä tee sitä.

7 Javadoc

7, 1 muotoilu

7, 1.1 yleinen muoto

javadocin blokkien perusmuotoilu on sama kuin tässä esimerkissä:

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

… tai tässä yksirivisessä esimerkissä:

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

perusmuoto on aina hyväksyttävä. Yksirivinen muoto voidaan korvata, kun Javadoc-lohkon koko (mukaan lukien kommenttimerkit) mahtuu yhdelle riville. Huomaa, että tämä pätee vain silloin, kun ei ole lohkotunnisteita, kuten @return.

7, 1.2 kappaleet

yksi tyhjä rivi—eli rivi, joka sisältää vain kohdistetun johtavan asteriskin(*)—näkyy kappaleiden välissä ja ennen lohkomerkkien ryhmää, jos esiintyy. Jokaisessa kappaleessa, mutta ensimmäisessä, on <p> välittömästi ennen ensimmäistä sanaa,eikä sen jälkeen ole tilaa.

7.1.3 Lohkotagit

mikä tahansa käytössä oleva standardi ”lohkotagit” esiintyvät järjestyksessä @param@return@throws@deprecated, ja nämä neljä tyyppiä eivät koskaan ilmesty tyhjällä kuvauksella. Kun lohkomerkki ei mahdu yhdelle riville, sisennetään jatkolinjat neljään (tai useampaan) välilyöntiin @.

7.2 tiivistelmäfragmentti

jokainen Javadoc-lohko alkaa lyhyellä tiivistelmäfragmentilla. Tämä muotoilu on erittäin tärkeää: se on ainoa osa tekstiä, joka esiintyy tietyissä yhteyksissä, kuten asclass ja method indexes.

Tämä on katkelma—substantiivilauseke tai verbilauseke, ei kokonainen lause. Se ei ala A {@code Foo} is a..., eikäThis method returns..., eikä se myöskään muodosta täydellistä imperatiivista sentencelikeä Save the record.. Katkelma on kuitenkin isolla alkukirjaimella kirjoitettu, ikään kuin se olisi kokonainen lause.

Vihje: yleinen virhe on kirjoittaa yksinkertainen Javadoc muodossa/** @return the customer ID */. Tämä ei pidä paikkaansa, vaan /** Returns the customer ID. */.

7.3 Jos Javadocia käytetään

minimissään, Javadocia on jokaisellapublic luokalla ja jokaisellapublic taiprotected tällaisen luokan jäsenellä, muutamia poikkeuksia lukuun ottamatta alla.

Javadoc-lisäpitoisuutta voi myös esiintyä, kuten kohdassa 7.3.4 selitetään,Ei-vaadittavaa Javadocia.

7.3.1 poikkeus: self-explanatory methods

Javadoc on valinnainen ”yksinkertaisille, ilmeisille” menetelmille, kutengetFoo, tapauksissa, joissa ei todellakaan ole mitään muuta sanottavaa kuin ”palauttaa foo”.

tärkeä: ei ole asianmukaista mainita tätä poikkeusta, jolla perustellaan merkitykselliset tiedot, jotka tyypillisen lukijan on ehkä tiedettävä. Esimerkiksi getCanonicalName, älä jätä pois sen dokumentaatiota(sillä perustelulla, että se sanoisi vain/** Returns the canonical name. */), jos tyypillisellä lukijalla ei ehkä ole mitään käsitystä siitä, mitä termi ”kanoninen nimi” tarkoittaa!

7.3.2 poikkeus: ohittaa

javadocia ei aina esiinny menetelmässä, joka ohittaa supertyypin menetelmän.

7.3.4 ei-pakollinen javadoc

muilla luokilla ja Jäsenillä on Javadoc tarpeen tai tarpeen mukaan.