1 Úvod

tento dokument slouží jako úplná definice standardů kódování Google forsource code v programovacím jazyce Java™. Zdrojový soubor Java je popsán jako inGoogle styl, pokud a pouze pokud dodržuje zde uvedená pravidla.

stejně jako ostatní Návody na programovací styl se tyto otázky týkají nejen estetických otázek formátování, ale i jiných typů konvencí nebo kódovacích standardů. Tento dokument se však soustřeďuje především na tvrdá a rychlá pravidla, která dodržujeme všeobecně, a dává rady, které nejsou jasně vymahatelné (ať už člověkem nebo nástrojem).

1.1 Terminologické poznámky

V tomto dokumentu, pokud není jinak upřesněno:

1. pojem třída se používá souhrnně rozumí „obyčejné“ třídy, enum, třída, rozhraní nebo typu anotace (@interface).
2. termín člen (třídy) se používá inkluzivně k označení vnořené třídy, pole, metody nebo konstruktoru; to znamená, že veškerý obsah třídy nejvyšší úrovně kromě inicializátorů a komentářů.
3. termín komentář vždy odkazuje na komentáře k implementaci. Nepoužíváme frázi „komentáře k dokumentaci“, místo toho používáme běžný termín “ Javadoc.“

Ostatní „terminologické poznámky“ se občas objeví v celém dokumentu.

1.2 průvodce poznámky

příklad kód v tomto dokumentu je non-normativní. To znamená, že zatímco příkladyjsou ve stylu Google, nemusí ilustrovat jediný stylový způsob, jak reprezentovatkód. Volitelné volby formátování provedené v příkladech by neměly být vynucovány jako pravidla.

2 Zdrojový soubor základy

2.1 název Souboru

zdrojový název souboru se skládá z případ-citlivé jméno top-level třídy obsahuje(z nichž je právě jeden), plus.java rozšíření.

2.2 kódování souboru: UTF-8

zdrojové soubory jsou zakódovány v UTF-8.

2.3 Speciální znaky

2.3.1 Prázdné znaky

Kromě zakončení řádku sekvence ASCII horizontální používá (0x20) je jediný prázdný znak, že appearsanywhere ve zdrojovém souboru. To znamená, že:

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

2.3.3 Non-ASCII znaků

Pro zbývající non-ASCII znaky, a to buď skutečné Unicode znak(např. ∞) nebo ekvivalent Unicode escape(např. \u221e). Volba závisí pouze onwhich dělá kód snadnější číst a rozumět, i když Unicode escapesoutside řetězcové literály a komentáře jsou důrazně nedoporučuje.

Tip: V případě úniku Unicode a občas i při použití skutečných znaků Unicode může být velmi užitečný vysvětlující komentář.

příklady:

Příklad:	Diskuse
String unitAbbrev = "μs";	Nejlepší: dokonale jasné, a to i bez komentáře.
String unitAbbrev = "\u03bcs"; // "μs"	povoleno, ale není důvod to dělat.
String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"	povoleno, ale trapné a náchylné k chybám.
String unitAbbrev = "\u03bcs";	Chudák: čtenář netuší, co to je.
return '\ufeff' + content; // byte order mark	dobrý: použijte escapy pro netisknutelné znaky a v případě potřeby komentujte.

Tip: Nikdy, aby váš kód méně čitelný, jednoduše ze strachu, kam až programy nemusí zvládnout non-ASCII znaky správně. Pokud k tomu dojde, typrogramy jsou rozbité a musí být opraveny.

3 struktura zdrojového souboru

Přesně jeden prázdný řádek odděluje jednotlivé sekce, která je přítomna.

3.1 informace o licenci nebo autorských právech, pokud jsou přítomny

Pokud licence nebo informace o autorských právech patří do souboru, patří sem.

3.2 Prohlášení o balíčku

prohlášení o balíčku není zabaleno do řádků. Omezení sloupce (Oddíl 4.4, omezení sloupce: 100) se nevztahuje na souhrny údajů.

3.3 příkazy importu

3.3.1 nepoužívají se žádné zástupné dovozy

zástupné dovozy, statické ani jiné.

3.3.2 no line-wrapping

příkazy importu nejsou line-wrapped. Omezení sloupce (Oddíl 4.4, omezení sloupce: 100) se nevztahuje na importní údaje.

3.3.3 řazení a mezery

dovozy jsou seřazeny následovně:

1. všechny statické importy V jednom bloku.
2. všechny nestatické importy V jednom bloku.

pokud existují statické i nestatické importy, odděluje jeden prázdný řádek dva bloky. Mezi příkazy importu nejsou žádné další prázdné řádky.

v každém bloku se importované názvy zobrazují v pořadí řazení ASCII. (Poznámka: Toto není stejné jako příkazy importu v pořadí řazení ASCII, protože ‚.“třídí před“;“.)

3.3.4 Žádný statický import pro třídy

statický import se nepoužívá pro statické vnořené třídy. Jsou dováženy s běžným dovozem.

3.4 deklarace třídy

3.4.1 přesně jedno deklarace třídy nejvyšší úrovně

každá třída nejvyšší úrovně je umístěna ve svém zdrojovém souboru.

3.4.2 objednání obsahu třídy

pořadí, které si vyberete pro členy a inicializátory vaší třídy, může mít velký vliv na learnability. Neexistuje však jediný správný recept, jak na to; různé třídy mohou svůj obsah různě upravovat.

důležité je, že každá třída používá nějaké logické pořadí, které by itsmaintainer mohl na požádání vysvětlit. Například, nové metody nejsou jen obvykle přidávány do endof třídy, protože by to přineslo“ chronologické podle data přidáno “ uspořádání, což není logické uspořádání.

3.4.2.1 přetížení: nikdy rozdělit

Když se třída má více konstruktérů, nebo více metod se stejným názvem, tyto appearsequentially, se žádný další kód v mezi (ani vlastním členům).

4 formátování

terminologie Poznámka: blokový konstrukt odkazuje na tělo třídy, metody nebo konstruktoru. Všimněte si, že, podle § 4.8.3.1 onarray inicializátory, žádné pole initializermay být případně zacházeno, jako kdyby to byl blok-jako konstrukt.

4.1 rovnátka

4.1.1 Závorky jsou používány tam, kde optional

Závorky jsou použity sifelsefordowhile prohlášení, i když thebody je prázdný nebo obsahuje pouze jeden výrok.

4.1.2 Neprázdné bloky: K & R styl

Rovnátka sledovat Kernighan a Ritchie styl(„Egyptské závorkách“)pro neprázdné bloky a blok-jako konstrukty:

• Žádné zalomení řádku před otevírací závorkou.
• přerušení řádku po otevření ortézy.
• přerušení řádku před uzavírací ortézou.
• přerušení řádku po závěrečné závorce, pouze pokud tato závorka ukončí příkaz nebo ukončí tělo metody, konstruktoru nebo pojmenované třídy. Například za ortézou není žádné přerušení řádku, pokud je následováno else nebo čárkou.

Příklady:

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ěkolik výjimek pro enum třídy jsou uvedeny v kapitole 4.8.1,Enum třídy.

4.1.3 prázdné bloky: může být stručné

prázdný blok nebo blokový konstrukt může být ve stylu k & R (jak je popsáno v sekci 4.1.2). Alternativně, může být uzavřena bezprostředně po jejím otevření, s žádné znaky nebo přerušení vedení mezi({}), pokud je součástí amulti-blok výkazu (ten, který přímo obsahuje několik bloků:if/else nebotry/catch/finally).

příklady:

 // 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 odsazení bloku: +2 mezery

pokaždé, když je otevřen nový blok nebo blokový konstrukt, odrážka se zvětší o dvěprostory. Když blok skončí, odsazení se vrátí na předchozí úroveň odsazení. Úroveň odsazení se vztahuje jak na kód, tak na komentáře v celém bloku. (Viz příklad V oddíle 4.1.2, Nonempty blocks: k & R Style.)

4.3 jeden příkaz na řádek

za každým příkazem následuje konec řádku.

4.4 sloupec limit: 100

Java kód má sloupec limit 100 znaků. „Znak“ znamená libovolný kódový bod Unicode.Kromě toho, jak je uvedeno níže, musí být každá čára, která by překročila tento limit, zabalena do čáry, jak je vysvětleno v oddíle 4.5.

každý kódový bod Unicode se počítá jako jeden znak, i když je jeho šířka zobrazení větší nebo menší. Například, pokud používátefullwidth znaky, můžete se rozhodnout zabalit řádek dříve, než kde toto pravidlo striktně vyžaduje.

Výjimky:

1. Řádky, kde poslouchali sloupec limit není možné (například, dlouhé URL v Javadoc, nebo dlouhou JSNI referenční metoda).
2. package a import prohlášení (viz oddíly 3.2 Prohlášení o balíčku a 3.3 prohlášení o importu).
3. příkazové řádky v komentáři, který může být vyříznut a vložen do shellu.

4.5 Linky-balení

Terminologie Poznámka: Pokud kód, který by jinak legallyoccupy jeden řádek je rozdělen do více řádků, tato činnost je calledline balení.

Neexistuje žádný komplexní, deterministický vzorec ukazuje, jak přesně zalamování řádek vkaždé situaci. Velmi často existuje několik platných způsobů, jak zabalit stejný kus kódu.

Poznámka: Zatímco typický důvod pro line-obal je avoidoverflowing sloupec limit, dokonce i kód, který by ve skutečnosti vešly ve sloupci omezení možná, line-zabalené v autorově uvážení.

Tip: extrahování metody nebo lokální proměnné může problém vyřešit bez nutnosti line-wrap.

4.5.1 kde zlomit

hlavní direktiva line-wrapingu je: raději zlomit na vyšší syntaktické úrovni. Také:

1. když je čára přerušena u operátora, který není přiřazen, je přestávka před symbolem. (Všimněte si, že toto není stejná praxe používaná ve stylu Google pro jiné jazyky, jako je C++ a JavaScript.)
   • To platí i pro následující „subjekt-jako“ symboly:
     • tečka oddělovač (.)
     • dvě dvojtečky metody referenční (::)
     • ampersand v typu vázán (<T extends Foo & Bar>)
     • trubka v bloku catch (catch (FooException | BarException e)).
2. Když linka je rozbité na operátor přiřazení přerušení obvykle přichází poté, co symbol, ale buď jak buď, je přijatelné.
   • to platí také pro dvojtečku „assignment-operator-like“ v rozšířeném příkazu for („foreach“).
3. název metody nebo konstruktoru zůstává připojen k otevřené závorce ((), která následuje.
4. čárka (,) zůstává připojena k tokenu, který jí předchází.
5. řádek není nikdy přerušen vedle šipky v lambda, kromě toho, že zlom může přijít bezprostředně za šipkou, pokud tělo lambda sestává z jediného neznačkového výrazu. Příklady:

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

Poznámka: primární cíl pro řádek balení je mít clearcode, ne nutně kód, který se vejde do nejmenší počet řádků.

4.5.2 Odrážka pokračování linky alespoň +4 místa

Když linky-balení, každý řádek po první (každé pokračování řádku) je indentedat nejméně +4 z původní linie.

Pokud existuje více pokračovacích řádků, odsazení se může měnit za + 4, Jak je požadováno. Obecně platí, že dvě pokračovací čáry používají stejnou úroveň odsazení, pokud a pouze pokud jsouzačínají syntakticky paralelními prvky.

oddíl 4.6.3 o adresách horizontálního zarovnání se nedoporučuje používat proměnný počet mezer k zarovnání určitých tokenů s předchozími liniemi.

4.6 Mezery

4.6.1 Vertikální Mezery

jeden prázdný řádek se zobrazí vždy

1. Mezi po sobě jdoucími členy nebo inicializátory třídy: pole, konstruktory, metody, vnořené třídy, statické inicializátory a inicializátory instancí.
   • výjimka: prázdný řádek mezi dvěma po sobě jdoucími poli (bez jiného kódu mezi nimi) je volitelný. Takové prázdné řádky se používají podle potřeby k vytvoření logických seskupení polí.
   • výjimka: prázdné čáry mezi konstantami výčtu jsou uvedeny v oddíle 4.8.1.
2. podle požadavků jiných částí tohoto dokumentu (například oddíl 3, struktura zdrojového souboru a oddíl 3.3, příkazy importu).

jediný prázdný řádek se také může objevit všude, kde zlepšuje čitelnost, například mezi údaji pro uspořádání kódu do logických podsekcí. Prázdný řádek před prvním členem orinitializer, nebo po posledním členem nebo inicializátor třídy, není podporována nordiscouraged.

Více po sobě jdoucích prázdných řádků je povoleno, ale nikdy není vyžadováno (nebo podporováno).

4.6.2 vodorovné mezery

mimo místa, kde to vyžaduje jazyk nebo jiná pravidla stylu, a kromě literálů, komentářů a javadoc se jediný ASCII prostor objeví také pouze na následujících místech.

1. Oddělení vyhrazené slovo, například iffor nebo catch, z otevřené závorka ((), které navazuje na linii
2. Oddělení vyhrazené slovo, například else nebo catch, z uzavírací složená závorka (}), které předchází to, že na řádek
3. Než otevřete složená závorka ({), s dvěma výjimkami:
   • @SomeAnnotation({a, b}) (bez mezery)
   • String x = {{"foo"}}; (žádné místo je nutné mezi {{ tím, že bod 8 níže)
4. Na obou stranách nějaké binární nebo ternární operátor. To platí i pro následující „subjekt-jako“ symboly:
   • ampersand v konjunktivní typ povinen: <T extends Foo & Bar>
   • potrubí na blok catch, který zpracovává více výjimek: catch (FooException | BarException e)
   • tlustého střeva (:) v rozšířené for („foreach“) prohlášení
   • šipky v lambda výraz: (String str) -> str.length()
   • dvě dvojtečky (::) metoda referenční, která je napsána jako Object::toString
   • tečka oddělovač (.), který je zapsán jako object.toString()
5. Po ,:; nebo uzavírací závorka ()) obsazení
6. Na obou stranách dvojité lomítko (//) že začíná end-of-line komentář. Zde je povoleno více mezer, ale není nutné.
7. Mezi typem a variabilní prohlášení: List<String> list
8. Volitelné uvnitř obou rovnátka pole inicializátor
   • new int {5, 6}new int { 5, 6 } jsou oba platné
9. Mezi typ anotace a nebo ....

toto pravidlo není nikdy interpretováno tak, že vyžaduje nebo zakazuje další místo na začátku nebo na začátku řádku; řeší pouze vnitřní prostor.

4.6.3 horizontální zarovnání: nikdy není nutné

poznámka k terminologii: Horizontální zarovnání jepraxe přidání variabilního počtu dalších mezer ve vašem kódu s cílem udělatněkteré žetony se objeví přímo pod některými dalšími žetony na předchozích řádcích.

tento postup je povolen, ale nikdy není vyžadován stylem Google. Nenídokonce je nutné udržovat vodorovné zarovnání v místech, kde již bylo použito.

Zde je příklad bez zarovnání, pak pomocí zarovnání:

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

Tip: Zarovnání může pomoci čitelnost, ale to vytváří problémy pro budoucí údržbu. Zvažte budoucí změnu, která se musí dotknout pouze jednoho řádku. Tato změna může zanechat dříve příjemné formátování rozbité, a to je povoleno. Častějipožádá kodér (možná vy), aby upravil mezery i na okolních řádcích, což by mohlo vést k kaskádové sérii přeformátování. Tato jednořádková změna má nyní „poloměr výbuchu“.“To může v nejhorším případě vést k zbytečné práci, ale v nejlepším případě stále poškozuje historii verzíinformace, zpomaluje recenzenty a zhoršuje konflikty sloučení.

4.7 seskupování závorek: doporučeno

Volitelné seskupení závorky jsou vynechány pouze tehdy, když autor a recenzent se shodují, že tam je noreasonable šance, že kód bude nesprávně vyložil bez nich, ani by učinily codeeasier číst. Není rozumné předpokládat, že každý čtenář má celou tabulku priorit Javaoperator zapamatovanou.

4.8 specifické konstrukce

4.8.1 třídy Enum

za každou čárkou, která následuje po konstantě enum, je konec řádku volitelný. Další prázdné řádky (obvykle jen jeden) jsou také povoleny. To je jedna z možností:

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

enum třídy bez metod a žádná dokumentace na jeho konstanty mohou být volitelně formattedas kdyby to bylo pole inicializátoru (viz Bod 4.8.3.1 onarray inicializátory).

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

protože třídy enum jsou třídy, platí všechna ostatní pravidla pro formátování tříd.

4.8.2 deklarace Proměnných

4.8.2.1 Jedné proměnné na prohlášení

Každý deklaraci proměnné (pole nebo místní) deklaruje pouze jednu proměnnou: prohlášení jakoint a, b; nejsou používány.

výjimka: Více proměnných deklarací je přijatelných v záhlaví smyčkyfor.

4.8.2.2 deklarované v případě potřeby

lokální proměnné nejsou obvykle deklarovány na začátku jejich containingbloku nebo blokové konstrukce. Místo toho jsou místní proměnné deklarovány blízko bodu, který jsouprvní použití (v rozumných mezích), aby se minimalizoval jejich rozsah. Deklarace lokálních proměnných obvykle majíinicializátory nebo jsou inicializovány ihned po deklaraci.

4.8.3 pole

4.8.3.1 inicializátory pole: může být „block-like“

jakýkoli inicializátor pole může být volitelně formátován, jako by to byl “ block-likeconstruct.“Například následující jsou platné (není 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 Č. C-style array prohlášení

hranaté závorky součástí typ, ne proměnné:String argsString args.

4.8.4 příkazy přepínače

terminologie Poznámka: uvnitř závorek bloku aswitch je jedna nebo více skupin příkazů. Každé prohlášení skupina se skládá jednoho nebo více spínače štítky (buď case FOO: nebodefault:), následuje jeden nebo více příkazů (nebo poslední prohlášení skupiny, nula nebo více výroky).

4.8.4.1 odsazení

stejně jako u jiných bloků je obsah spínacího bloku odsazen +2.

po štítku přepínače dojde k přerušení řádku a úroveň odsazení se zvýší + 2, přesnějako kdyby byl blok otevřen. Následující štítek přepínače se vrátí k předchozímu odsazeníúroveň, jako by byl blok uzavřen.

4.8.4.2 pokles: poznamenal,

Ve switch bloku, každé prohlášení skupiny buď ukončí náhle (sbreakcontinuereturn nebo je vyvolána výjimka), nebo je označen commentto naznačují, že provedení bude nebo by mohla pokračovat do další prohlášení skupiny. Postačuje jakýkoli komentář, který sděluje myšlenku propadu (typicky// fall through). Tento zvláštní komentář se nevyžadujeposlední skupina příkazů spínacího bloku. Příklad:

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

Všimněte si, že žádný komentář, je potřeba po case 1:, onlyat konci prohlášení skupiny.

4.8.4.3 default případě, že je přítomen

Každý příkaz switch obsahuje default statementgroup, i když to neobsahuje žádný kód.

Výjimka: příkaz switch pro enum typu může omitthe default prohlášení skupiny, pokud to includesexplicit případech pokrývá všechny možné hodnoty tohoto typu. To umožňuje IDE nebo jiné nástroje staticanalysis vydat varování, pokud byly některé případy vynechány.

4.8.5 anotace

anotace vztahující se na třídu, metodu nebo Konstruktor se objeví bezprostředně za Dokumentačním blokem a každá anotace je uvedena na vlastním řádku (tj. na jednom řádku anotace). Tyto zlomy čáry nepředstavují obtékání čáry (Řez4. 5, obtékání čáry), takže úroveň odsazení není zvýšena. Příklad:

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

výjimka: Jeden parameterless annotationmay místo toho se objeví spolu s prvním řádku podpis, například:

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

Popisy vztahující se na poli objeví také ihned po dokumentaci bloku, ale v tomto případě, více anotací (případně parametry) mohou být uvedeny na stejném řádku, například:

@Partial @Mock DataLoader loader;

Tam jsou žádná zvláštní pravidla pro formátování poznámek na parametry, lokální proměnné, nebo typy.

tato část se zabývá komentáři k implementaci. Javadoc je řešen samostatně včást 7, Javadoc.

jakémukoli přerušení řádku může předcházet libovolné mezery následované komentářem k implementaci.Takový komentář způsobí, že řádek není prázdný.

4.8.6.1 Styl Komentáře bloku

Komentáře bloku jsou odsazeny na stejné úrovni jako okolní kód. Mohou být v/* ... */ style nebo// ... style. Pro multi-line/* ... */ komentáře, následující řádky musí začínat* sladěny s * na předchozím řádku.

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

Komentáře nejsou uzavřeny v kolonkách s hvězdičkami nebo jinými znaky.

Tip: Při psaní multi-linka komentáře, použijte/* ... */ styl pokud chcete, automatické kód formátovače tore-wrap řádky, když je to nutné (bod-styl). Většina formátovačů neopravuje řádky v// ... bloky komentářů ve stylu.

4.8.7 Modifikátory

Třídy a členské modifikátory, pokud je přítomen, objeví se v orderrecommended pomocí Java Language Specification:

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

4.8.8 Číselné Literály

longhodnotou celočíselné literály použít velká písmena L přípony, neverlowercase (aby nedošlo k záměně s číslicí, 1). Například 3000000000Lspíše než 3000000000l.

5 pojmenování

5.1 pravidla společná všem identifikátorům

identifikátory používají pouze písmena a číslice ASCII a v malém počtu níže uvedených případů podtržítka. Každý platný název identifikátoru je tedy přiřazen regulárním výrazem\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.

názvy tříd jsou typicky podstatná jména nebo fráze podstatných jmen. NapříkladCharacter neboImmutableList. Názvy rozhraní může být také podstatná jména ornoun fráze (například List), ale někdy může beadjectives nebo adjektivum fráze místo (napříkladReadable).

neexistují žádná specifická pravidla nebo dokonce dobře zavedené konvence pro pojmenování typů anotací.

testovací třídy jsou pojmenovány počínaje názvem třídy, kterou testují, a končící Test. NapříkladHashTest neboHashIntegrationTest.

5.2.3 názvy metod

názvy metod jsou zapsány v lowerCamelCase.

názvy metod jsou typicky slovesa nebo slovesné fráze. NapříkladsendMessage nebostop.

podtržítka se mohou objevit v názvech testovacích metod JUnit pro oddělení logických komponent jména, přičemž každá komponenta je zapsána v lowerCamelCase.Jeden typický vzor je <methodUnderTest>_<state>, například pop_emptyStack. Neexistuje nikdo Správnýzpůsob, jak pojmenovat zkušební metody.

5.2.4 konstantní názvy

konstantní názvy používají CONSTANT_CASE: všechny uppercaseletters, přičemž každé slovo je odděleno od dalšího jediným podtržítkem. Ale co je aconstant, přesně tak?

konstanty jsou statická konečná pole, jejichž obsah je hluboce neměnný a jejichž metody mají nezjistitelné vedlejší účinky. To zahrnuje primitivy, řetězce, neměnné typy a neměnnésbírky neměnných typů. Pokud se některý z pozorovatelných stavů instance může změnit, není trvalý. Pouhý úmysl nikdy nemutovat objekt nestačí. Příklad:

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

tato jména jsou typicky podstatná jména nebo podstatné fráze.

5.2.5 nekonstantní názvy polí

nekonstantní názvy polí (statické nebo jiné) se zapisují do lowerCamelCase.

tato jména jsou obvykle podstatná jména nebo fráze podstatných jmen. NapříkladcomputedValues neboindex.

5.2.6 názvy parametrů

názvy parametrů jsou zapsány v lowerCamelCase.

je třeba se vyhnout Jednoznakovým názvům parametrů ve veřejných metodách.

5.2.7 Názvy lokálních proměnných

Názvy lokálních proměnných se zapisují do lowerCamelCase.

i když jsou konečné a neměnné, místní proměnné nejsou považovány za konstanty a neměly by být stylizovány jako konstanty.

5.2.8 Zadejte názvy proměnných,

Každý typ proměnné je jmenován v jednom ze dvou stylů:

• jediné velké písmeno, volitelně následovaný jednotlivé číslice (např. ETXT2)
• jméno v podobě používá pro třídy (viz Oddíl 5.2.2, názvy tříd), následuje velké písmeno T (příklady: RequestTFooBarT).

5.3 Camel case: definovanými

Někdy je více než jeden rozumný způsob, jak převést anglické fráze do velblouda případ,jako když zkratek nebo neobvyklé konstrukce, jako „IPv6“ nebo „iOS“ jsou přítomny. Chcete-li zlepšitpředvídatelnost, Styl Google určuje následující (téměř) deterministické schéma.

počínaje prózou názvu:

1. převeďte frázi na prostý ASCII a odstraňte všechny apostrofy. Například „Müllerův algoritmus“ se může stát „muellerovým algoritmem“.
2. rozdělte tento výsledek na slova, rozdělte na mezery a zbývající interpunkci(obvykle spojovníky).
   • Doporučená: pokud nějaké slovo má již konvenční camel-case vzhled v běžné použití, rozdělení na jednotlivé části (např., „AdWords“ se stává „reklamní slova“). Všimněte si, že slovo jako “ iOS “ není ve skutečnosti v případě velblouda samo o sobě; odporuje jakékoli konvenci, takže toto doporučení neplatí.
3. nyní malými písmeny vše (včetně zkratek), pak velkými písmeny pouze první znak:
   • … každé slovo, čímž se získá velká písmena velblouda, nebo
   • … každé slovo s výjimkou první, se výnos nižší velbloud
4. a Konečně, připojit všechna slova do jednoho identifikátoru.

Všimněte si, že obal původních slov je téměř zcela ignorován. Příklad:

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: vždy se používá

metoda je označena @Override annotationwhenever it is legal. To zahrnuje třídy metodu přepsání nadtřídy, třídy methodimplementing rozhraní metodu, a to metodu rozhraní respecifying a superinterfacemethod.

Výjimka:@Override může být vynechán, když rodič metoda je@Deprecated.

6.2 chycené výjimky: není ignorováno

kromě toho, jak je uvedeno níže, je velmi zřídka správné nedělat nic v reakci na caughtexception. (Typickými odpověďmi je protokolování, nebo pokud je považováno za „nemožné“, přehodnoťte jej jakoAssertionError.)

Pokud je skutečně vhodné v bloku odlovu podniknout žádné kroky, je důvod, proč je to odůvodněné, vysvětlen v komentáři.

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

Výjimka: V testech, chytil výjimkou může být ignoredwithout komentář, pokud jeho jméno je nebo začíná s expected. Thefollowing je velmi běžný idiom pro zajištění toho, aby testovaný kód hodil anexception očekávaného typu, takže komentář je zde zbytečný.

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

6.3 Statické členy: kvalifikovaná pomocí třídy

Když odkaz na statický člen třídy musí být kvalifikovaný, je kvalifikovaným se, že třída’sname, ne s odkazem nebo vyjádření, že třída je typ.

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

6.4 Finalizers: nepoužívá se

je extrémně vzácné přepsat Object.finalize.

Tip: nedělejte to. Pokud je to nezbytně nutné, nejprve si velmi pečlivě přečtěte a pochopte efektivní položku Java 7,“Vyhněte se Finalizátorům“, a pak to nedělejte.

7 Javadoc

7.1 formátování

7.1.1 obecný formulář

základní formátování bloků Javadoc je vidět v tomto příkladu:

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

… nebo v tomto příkladu s jedním řádkem:

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

základní formulář je vždy přijatelný. Jednořádkový formulář může být nahrazen, pokud se celý blok Javadoc (včetně značek komentářů) vejde na jeden řádek. Všimněte si, že to platí pouze v případě, že neexistují žádné blokové značky, jako je @return.

7.1.2 Body

Jeden prázdný řádek—to je, za řádek obsahující pouze zarovnány vedoucí hvězdička(*)—objeví se mezi body a před skupiny blok kategorie ifpresent. Každý odstavec, ale první má <p> bezprostředně před prvním slovem, bez mezery po.

7.1.3 Blokové tagy

standardní „blokové tagy“, které jsou používány, se zobrazí v pořadí @param@return@throws@deprecated, a tyto čtyři typy neverappear s prázdný popisek. Pokud se značka bloku nevejde na jeden řádek, pokračovací řádkyjsou odsazeny čtyři (nebo více) mezery z pozice @.

7.2 souhrnný fragment

každý blok Javadoc začíná stručným souhrnným fragmentem. Thisfragment je velmi důležitý: je to jediná část textu, která se objevuje v určitých kontextech, jako jetřídy a indexy metod.

Jedná se o fragment-podstatnou frázi nebo slovesnou frázi, nikoli úplnou větu. To doesnot začít s A {@code Foo} is a... neboThis method returns..., ani to tvoří kompletní imperativ sentencelike Save the record.. Fragment je však kapitalizován apředloženo, jako by to byla úplná věta.

Tip: častou chybou je napsat jednoduchý Javadoc ve tvaru/** @return the customer ID */. Toto je nesprávné a mělo by býtzměněn na /** Returns the customer ID. */.

7.3, Kde Javadoc používá

Na minimum, Javadoc je přítomen pro každýpublic třídy, a každýpublic neboprotected členské takové třídy, s několika exceptionsnoted níže.

může být také přítomen další obsah Javadoc, jak je vysvětleno v bodě 7.3.4, Nevyžadovaný Javadoc.

7.3.1 Výjimkou: self-vysvětlující metody

Javadoc je volitelné pro „jednoduché, jasné“ metody, jako jegetFoo, v případech, kde je opravdu a skutečně isnothing ještě stojí za to říct, ale „Vrátí foo“.

důležité: není vhodné citovat tuto výjimku z důvodu odůvodnění relevantních informací, které by typický čtenář mohl potřebovat znát. Například pro methodnamed getCanonicalName, ne vynechat své dokumentace(s odůvodněním, že to by řekl jen/** Returns the canonical name. */) je-li typický čtenář může mít tušení, co pojem „kanonický název“ znamená!

7.3.2 výjimka: přepíše

Javadoc není vždy přítomen na metodě, která přepíše metodu supertypu.

7.3.4 nevyžaduje Javadoc

ostatní třídy A členové mají Javadoc podle potřeby nebo přání.