1 Wprowadzenie

ten dokument służy jako pełna definicja standardów kodowania Google dla kodu źródłowego w języku programowania Java™. Plik źródłowy Java jest opisany jako w stylu inGoogle wtedy i tylko wtedy, gdy przestrzega zasad zawartych w niniejszym dokumencie.

podobnie jak inne przewodniki po stylach programowania, zagadnienia obejmowały nie tylko kwestie estetyczne, ale także inne typy konwencji czy standardów kodowania. Jednak dokument ten koncentruje się przede wszystkim na twardych i szybkich zasadach, których przestrzegamy powszechnie, i unika udzielania porad, które nie są wyraźnie egzekwowalne (czy to przez człowieka, czy narzędzie).

1.1 uwagi dotyczące terminologii

w niniejszym dokumencie, o ile nie określono inaczej:

1. termin klasa jest używany łącznie do oznaczenia „zwykłej” klasy, klasy enum, interfejsu lub typu adnotacji (@interface).
2. termin element (klasy) jest używany łącznie do oznaczania zagnieżdżonej klasy, pola, metody lub konstruktora; oznacza to, że cała zawartość najwyższego poziomu klasy z wyjątkiem inicjalizatorów i komentarzy.
3. termin komentarz zawsze odnosi się do komentarzy implementacyjnych. Nie używamy wyrażenia „documentation comments”, zamiast tego używamy wspólnego terminu ” Javadoc.”

inne” uwagi terminologiczne ” pojawią się sporadycznie w całym dokumencie.

1.2 uwagi do przewodnika

przykładowy kod w tym dokumencie jest nienormatywny. Oznacza to, że chociaż przykłady są w stylu Google, mogą nie ilustrować jedynego stylowego sposobu reprezentowania kodu. Opcjonalne wybory formatowania dokonane w przykładach nie powinny być egzekwowane jako reguły.

2 Podstawy pliku źródłowego

2.1 Nazwa pliku

nazwa pliku źródłowego składa się z rozróżniającej wielkość liter nazwy klasy najwyższego poziomu, w której jest dokładnie jedna, plus.java rozszerzenia.

2.2 kodowanie plików: UTF-8

pliki źródłowe są zakodowane w UTF-8.

2.3 znaki specjalne

2.3.1 znaki spacji

poza sekwencją zakończenia linii, znak spacji poziomej ASCII (0x20) jest jedynym znakiem spacji, który pojawia się w pliku źródłowym. Oznacza to, ż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)

2.3.3 znaki inne niż ASCII

dla pozostałych znaków innych niż ASCII używany jest rzeczywisty znak Unicode(np.∞) lub równoważna Ucieczka Unicode(np.\u221e). Wybór zależy tylko od tego, co sprawia, że kod jest łatwiejszy do odczytania i zrozumienia, chociaż Unicode ucieka poza literałami ciągów i komentarze są zdecydowanie odradzane.

Wskazówka: W przypadku escape Unicode, a czasami nawet gdy używane są znaki actualUnicode, komentarz wyjaśniający może być bardzo pomocny.

przykłady:

String unitAbbrev = "\u03bcs"; // "μs"

String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"

String unitAbbrev = "\u03bcs";

return '\ufeff' + content; // byte order mark

przykład	dyskusja
String unitAbbrev = "μs";	najlepszy: doskonale przejrzysty nawet bez komentarza.
dozwolone, ale nie ma powodu, aby to robić.
dozwolone, ale niezręczne i podatne na błędy.
słabe: czytelnik nie ma pojęcia, co to jest.
dobre: użyj znaków specjalnych dla znaków niedrukowalnych i w razie potrzeby komentuj.

Wskazówka: nigdy nie zmniejszaj czytelności kodu z obawy, że niektóre programy mogą nie obsługiwać poprawnie znaków innych niż ASCII. Jeśli tak się stanie, teprogramy są zepsute i muszą zostać naprawione.

3 Struktura pliku źródłowego

dokładnie jedna pusta linia oddziela każdą istniejącą sekcję.

3.1 informacje o licencji lub prawach autorskich, jeśli są obecne

Jeśli informacje o licencji lub prawach autorskich należą do pliku, należy tutaj.

3.2 Instrukcja Package

Instrukcja package nie jest owinięta wierszem. Limit kolumn (sekcja 4.4,limit kolumn: 100) nie ma zastosowania do instrukcji pakietu.

3.3 polecenia importu

3.3.1 nie stosuje się importu symboli wieloznacznych

importu symboli wieloznacznych, statycznego lub innego.

3.3.2 brak zawijania linii

polecenia importu nie są zawijane w linie. Limit kolumn (sekcja 4.4,limit kolumn: 100) nie ma zastosowania do elementów importu.

3.3.3 kolejność i odstępy

Import jest uporządkowany w następujący sposób:

1. wszystkie importy statyczne w jednym bloku.
2. wszystkie importy niestatyczne w jednym bloku.

Jeśli są importowane zarówno statyczne, jak i niestatyczne, pojedyncza pusta linia oddziela dwie blokady. Nie ma innych pustych linii między instrukcjami importu.

w każdym bloku zaimportowane nazwy są wyświetlane w kolejności sortowania ASCII. (Uwaga: to nie jest to samo, co polecenia importu są w porządku sortowania ASCII, ponieważ”.’sorts before’;’.)

3.3.4 brak statycznego importu dla klas

statyczny import nie jest używany dla statycznych klas zagnieżdżonych. Są importowane z normalnym importem.

3.4 deklaracja klasy

3.4.1 dokładnie jedna deklaracja klasy najwyższego poziomu

każda klasa najwyższego poziomu znajduje się w pliku źródłowym.

3.4.2 uporządkowanie zawartości klasy

kolejność, którą wybierzesz dla członków i inicjatorów twojej klasy, może mieć duży wpływ na jej dostępność. Jednak nie ma jednej właściwej recepty na to, jak to zrobić; różne klasy mogą zamawiać swoje treści na różne sposoby.

ważne jest to, że każda klasa używa jakiegoś logicznego porządku, który jej opiekun mógłby wyjaśnić, jeśli zapyta. Na przykład, nowe metody nie są zwyczajowo dodawane do końca klasy, ponieważ dałoby to porządek „chronologiczny według daty dodania”, co nie jest logicznym porządkowaniem.

3.4.2.1 przeciążenia: nigdy nie dziel

, gdy klasa ma wiele konstruktorów lub wiele metod o tej samej nazwie, pojawiają się one kolejno, bez żadnego innego kodu pomiędzy (nawet członków prywatnych).

4 formatowanie

Uwaga dotycząca terminologii: konstrukcja blokowa odnosi się do ciała klasy, metody lub konstruktora. Zauważ, że w sekcji 4.8.3.1 inicjalizatory onarray, Dowolna inicjalizacja tablicy może być opcjonalnie traktowana tak, jakby była konstrukcją podobną do bloku.

4, 1.1 szelki są używane, gdy opcjonalne

szelki są używane zifelsefordo Iwhile polecenia, nawet gdy thebody jest puste lub zawiera tylko jedno polecenie.

4.1.2 Nonempty blocks: K& R style

nawiasy klamrowe podążają za stylem Kernighan i Ritchie(„egipskie nawiasy klamrowe”)dla bloków nonempty i konstrukcji blokowych podobnych:

• brak przerwania linii przed nawiasem otwierającym.
• przerwa w linii po nawiasie otwierającym.
• przerwa linii przed nawiasem zamykającym.
• podział linii po nawiasie zamykającym, tylko wtedy, gdy ten nawias kończy polecenie lub kończy ciało metody, konstruktora lub nazwanej klasy. Na przykład, nie ma przerwania linii po nawiasie, jeśli po nim następuje else lub przecinek.

przykłady:

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

kilka wyjątków dla klas enum podano w sekcji 4.8.1,klasy Enum.

4.1.3 puste bloki: może być zwięzły

pusty blok lub konstrukcja blokowa może być w stylu K & R (zgodnie z opisem inSection 4.1.2). Alternatywnie, może być zamknięty natychmiast po otwarciu, bez znaków lub przerwy między wierszami({}), chyba że jest częścią instrukcji amulti-block (która bezpośrednio zawiera wiele bloków:if/else lubtry/catch/finally).

przykłady:

 // 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 wcięcie bloku: +2 spacje

za każdym razem, gdy otwiera się nowy blok lub konstrukcję podobną do bloku, wcięcie zwiększa się o dwa spacje. Po zakończeniu bloku wcięcie powraca do poprzedniego poziomu wcięć. Poziom wcięć dotyczy zarówno kodu, jak i komentarzy w całym bloku. (Zobacz przykład w sekcji 4.1.2,bloki Nonempty: K& R Style.)

4.3 po jednej instrukcji na linię

Po każdej instrukcji następuje podział linii.

4.4 limit kolumn: 100

Kod Javy ma limit kolumn 100 znaków. „Znak” oznacza dowolny punkt kodu Unicode.Z wyjątkiem przypadków wymienionych poniżej, każda linia, która przekroczyłaby ten limit, musi być owinięta liną, jak wyjaśniono w sekcji 4.5, owinięcie liną.

każdy punkt kodu Unicode liczy się jako jeden znak, nawet jeśli jego szerokość wyświetlania jest większa lub mniejsza. Na przykład, jeśli używasz znaków fillwidth, możesz zawinąć linię wcześniej niż wymaga tego ta reguła.

wyjątki:

1. wiersze, w których przestrzeganie limitu kolumn nie jest możliwe (na przykład długi adres URL w Javadoc lub długie odniesienie do metody Jsni).
2. package Iimport instrukcje (patrz sekcje 3.2 instrukcje pakietu i 3.3 instrukcje importu).
3. linie poleceń w komentarzu, które mogą być wycięte i wklejone do powłoki.

4.5 zawijanie linii

Uwaga dotycząca terminologii: gdy kod, który w przeciwnym razie mógłby zostać podzielony na kilka linii, czynność ta nazywa się zawijaniem linii.

nie ma kompleksowej, deterministycznej formuły pokazującej dokładnie, jak zawinąć linię w danej sytuacji. Bardzo często istnieje kilka ważnych sposobów zawijania tego samego fragmentu kodu.

Uwaga: podczas gdy typowym powodem zawijania linii jest unikanie przepuszczania limitu kolumn, nawet kod, który w rzeczywistości zmieściłby się w granicach kolumn, może być owinięty wierszem według uznania autora.

Wskazówka: wyodrębnienie metody lub zmiennej lokalnej może rozwiązać problem bez konieczności zawijania linii.

4.5.1 gdzie łamać

główną dyrektywą zawijania linii jest: preferuj łamanie na wyższym poziomie składniowym. Również:

1. gdy linia jest łamana przy operatorze niezwiązanym z przypisaniem, łamanie pojawia się przed symbolem. (Zauważ, że nie jest to ta sama praktyka stosowana w stylu Google dla innych języków, takich jak C++ i JavaScript.)
   • dotyczy to również następujących symboli „podobnych do operatora”:
     • separator kropek (.)
     • dwa dwukropki odniesienia metody (::)
     • ampersand w powiązaniu typu (<T extends Foo & Bar>)
     • rura w bloku zatrzaskowym (catch (FooException | BarException e)).
2. gdy linia jest łamana przy operatorze przypisania, łamanie zwykle następuje po symbolu, ale w obu przypadkach jest dopuszczalne.
   • dotyczy to również dwukropka „assignment-operator-like” w ulepszonej instrukcjifor („foreach”).
3. nazwa metody lub konstruktora pozostaje dołączona do otwartego nawiasu ((), który następuje po niej.
4. przecinek (,) pozostaje dołączony do tokenu, który go poprzedza.
5. linia nigdy nie jest łamana obok strzałki w lambdzie, z wyjątkiem tego, że przerwa może nastąpić bezpośrednio po strzałce, jeśli ciało lambdy składa się z pojedynczego niezablokowanego wyrażenia. Przykłady:

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

Uwaga: głównym celem zawijania linii jest posiadanie clearcode, niekoniecznie kodu, który mieści się w najmniejszej liczbie linii.

4.5.2 Wcięcie linie kontynuujące co najmniej +4 spacje

podczas zawijania linii, każda linia po pierwszej (każda linia kontynuująca) jest wcięta co najmniej +4 od linii oryginalnej.

gdy istnieje wiele linii kontynuacji, wcięcia mogą być zmieniane poza +4. Na ogół dwie linie kontynuacyjne używają tego samego poziomu wcięcia wtedy i tylko wtedy, gdy są połączone ze składniowo równoległymi elementami.

sekcja 4.6.3 dotycząca wyrównania poziomego adresuje zniechęconą praktykę używania zmiennej liczby spacji do wyrównywania niektórych tokenów z poprzednimi liniami.

4.6 białe znaki

4.6.1 pionowe białe znaki

zawsze pojawia się pojedyncza pusta linia:

1. między kolejnymi członkami lub inicjalizatorami klasy: pola, konstruktory, metody, klasy zagnieżdżone, statyczne inicjalizatory i inicjalizatory instancji.
   • wyjątek: pusta linia między dwoma kolejnymi polami (bez innego kodu między nimi) jest opcjonalna. Takie puste linie są używane w razie potrzeby do tworzenia logicznych grup pól.
   • wyjątek: puste linie między stałymi enum są opisane w sekcji 4.8.1.
2. zgodnie z wymaganiami innych sekcji tego dokumentu (takich jak sekcja 3, struktura plików źródłowych i sekcja 3.3, instrukcje importu).

pojedyncza pusta linia może również pojawić się wszędzie tam, gdzie poprawia to czytelność, na przykład w celu uporządkowania kodu w logiczne podrozdziały. Pusta linia przed pierwszym członem lub inicjalizatorem, lub po ostatnim członie lub inicjalizatorze klasy, nie jest zachęcana.

wiele kolejnych pustych linii jest dozwolonych, ale nigdy nie jest wymagane (lub zalecane).

4.6.2 poziome spacje

poza miejscami wymaganymi przez język lub inne reguły stylu, a poza literałami, komentarzami i komentarzami, pojedyncza spacja ASCII pojawia się również tylko w następujących miejscach.

1. oddzielenie dowolnego słowa zarezerwowanego, takiego jak iffor lub catch, od otwartego nawiasu ((), który podąża za nim w tej linii
2. oddzielenie dowolnego słowa zarezerwowanego, takiego jak else lub catch, od zamykającej klamry (}), które poprzedza je w tej linii
3. przed dowolnym otwartym klamrą ({), z dwoma wyjątkami:
   • @SomeAnnotation({a, b}) (nie jest używana spacja)
   • String x = {{"foo"}}; (nie jest wymagana spacja między{{, według pozycji 8 poniżej)
4. po obu stronach dowolnego operatora binarnego lub trójskładnikowego. Dotyczy to również następujących symboli „podobnych do operatora”:
   • ampersand w powiązaniu typu: <T extends Foo & Bar>
   • Rura dla bloku zatrzaskowego, który obsługuje wiele wyjątków: catch (FooException | BarException e)
   • dwukropek (:) w ulepszonej instrukcjifor („foreach”)
   • strzałka w wyrażeniu lambda: (String str) -> str.length()

   ale nie

   • dwa dwukropki (::) odniesienia do metody, która jest zapisana jak Object::toString
   • separator kropek (.), który jest zapisany jak object.toString()
5. po ,:; lub nawias zamykający ()) rzutu
6. po obu stronach podwójnego ukośnika (//), który rozpoczyna komentarz na końcu wiersza. W tym przypadku dopuszcza się wiele spacji, ale nie jest to wymagane.
7. pomiędzy typem i zmienną deklaracji:List<String> list
8. opcjonalne tylko wewnątrz obu nawiasów inicjalizatora tablicy
   • new int {5, 6} Inew int { 5, 6 } są ważne
9. między adnotacją typu a lub....

reguła ta nigdy nie jest interpretowana jako wymagająca lub zakazująca dodatkowej przestrzeni na początku lub początku linii; dotyczy tylko przestrzeni wewnętrznej.

4.6.3 wyrównanie poziome: nigdy nie jest wymagane

Uwaga dotycząca terminologii: Wyrównanie poziome to praktyka dodawania zmiennej liczby dodatkowych spacji w kodzie w celu uczynienia pewnych tokenów pojawiających się bezpośrednio pod niektórymi innymi tokenami w poprzednich wierszach.

ta praktyka jest dozwolona, ale nigdy nie jest wymagana przez Styl Google. Nie jest wymagane utrzymanie wyrównania poziomego w miejscach, w których był już używany.

oto przykład bez wyrównania, a następnie za pomocą wyrównania:

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

Wskazówka: wyrównanie może pomóc w czytelności, ale stwarza problemy dla przyszłej konserwacji. Rozważ przyszłą zmianę, która musi dotknąć tylko jednej linii. Ta zmiana może spowodować zniekształcenie formatowania, co jest dozwolone. Częściej monituje koder (być może ty) o dostosowanie spacji również w pobliskich liniach, możliwe, że uruchomi kaskadową serię formatowań. Ta jednowierszowa zmiana ma teraz ” promień wybuchu.”Może to w najgorszym przypadku skutkować bezsensowną pracą, ale w najlepszym razie nadal psuje historię wersji, spowalnia recenzentów i zaostrza konflikty merge.

4.7 nawiasy Grupowe: zalecane

opcjonalne nawiasy grupujące są pomijane tylko wtedy, gdy autor i recenzent zgadzają się, że nie ma możliwej szansy, że kod zostanie błędnie zinterpretowany bez nich, ani nie uczyniliby kodu łatwiejszym do odczytania. Nie jest rozsądne zakładać, że każdy czytelnik ma zapamiętaną całą tabelę pierwszeństwa Javaoperator.

4.8 specyficzne konstrukcje

4.8.1 klasy Enum

Po każdym przecinku, który następuje po stałej enum, podział linii jest opcjonalny. Dozwolone są również dodatkowe puste linie (zwykle tylko jeden). Jest to jedna z możliwości:

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

Klasa enum bez metod i dokumentacji jej stałych może być opcjonalnie formatowana, jeśli była inicjalizatorem tablicy (patrz punkt 4.8.3.1 inicjalizatory onarray).

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

ponieważ klasy enum są klasami, obowiązują wszystkie inne reguły formatowania klas.

4.8.2 deklaracje zmiennych

4.8.2.1 jedna zmienna na deklarację

każda deklaracja zmiennych (polowa lub lokalna) deklaruje tylko jedną zmienną: deklaracje takie jakint a, b; nie są używane.

: Wielokrotne deklaracje zmiennych są dopuszczalne w nagłówku pętlifor.

4.8.2.2 deklarowane w razie potrzeby

zmienne lokalne nie są zwykle deklarowane na początku ich konstrukcji typu containingblock lub block-like. Zamiast tego, zmienne lokalne są deklarowane blisko punktu, w którym są najpierw używane (w granicach rozsądku), aby zminimalizować ich zakres. Deklaracje zmiennych lokalnych zazwyczaj mają inicjalizatory lub są inicjowane bezpośrednio po deklaracji.

4.8.3 Tablice

4.8.3.1 inicjalizatory tablic: może być „Block-like”

dowolny inicjalizator tablicy może być opcjonalnie sformatowany tak, jakby był „Block-likeconstruct.”Na przykład wszystkie poprawne (nie lista wyczerpująca) są następujące:

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 brak deklaracji tablicy w stylu C

nawiasy kwadratowe stanowią część typu, a nie zmienną:String args, nieString argsdiv>.

4.8.4 instrukcje Switch

Uwaga dotycząca terminologii: wewnątrz nawiasów klamrowych bloku aswitch znajduje się jedna lub więcej grup instrukcji. Każda grupa instrukcji składa się z jednej lub więcej etykiet przełączników (case FOO: lubdefault:), po których następuje jedno lub więcej instrukcji (lub, w przypadku ostatniej grupy instrukcji, zero lub więcej instrukcji).

4.8.4.1 wcięcia

jak w przypadku każdego innego bloku, Zawartość bloku przełącznika jest wcięta +2.

po etykiecie przełącznika następuje przerwa w linii, a poziom wcięcia zwiększa się +2, dokładnie jeśli blok był otwierany. Następująca Etykieta przełącznika powraca do poprzedniego poziomu wcięcia, tak jakby blok został zamknięty.

4.8.4.2: skomentowany

w bloku przełącznika każda grupa instrukcji kończy się nagle (zbreakcontinuereturn lub wyrzuconym wyjątkiem), lub jest oznaczony komentarzem wskazującym, że wykonanie będzie lub może być kontynuowane w następnej grupie instrukcji. Wystarczy dowolna kommentacja komunikująca ideę fall-through (zazwyczaj// fall through). Ten specjalny komentarz nie jest wymagany w ostatniej grupie instrukcji bloku switch. Przykład:

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

zauważ, że nie jest potrzebny komentarz pocase 1:, tylko na końcu grupy instrukcji.

4.8.4.3default case is present

każda instrukcja switch zawieradefault statementgroup, nawet jeśli nie zawiera kodu.wyjątek

: Instrukcja switch dla typuenum może pominąć grupę instrukcjidefault, jeśli zawiera przypadki, w których występują wszystkie możliwe wartości tego typu. Umożliwia to IDE lub innym narzędziom do analizy statycznej wystawianie ostrzeżenia, jeśli jakiekolwiek przypadki zostały pominięte.

4.8.5 adnotacje

adnotacje mające zastosowanie do klasy, metody lub konstruktora pojawiają się natychmiast po bloku dokumentacji, a każda adnotacja jest wyświetlana w osobnej linii (czyli jednej linii adnotacji). Te podziały linii nie stanowią owijania linii (sekcja 4.5, owijanie linii), więc poziom wcięć nie jest zwiększany. Przykład:

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

wyjątek: Pojedyncza, nieparametryczna adnotacja może zamiast tego pojawić się razem z pierwszym wierszem podpisu, na przykład:

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

adnotacje dotyczące pola pojawiają się również bezpośrednio po bloku dokumentacji, ale w tym przypadku wiele adnotacji (ewentualnie sparametryzowanych) może być wyświetlonych w tym samym wierszu;na przykład:

@Partial @Mock DataLoader loader;

nie ma specjalnych reguł do formatowania adnotacji na parametrach, zmiennych lokalnych lub typach.

Ta sekcja dotyczy komentarzy do implementacji. Javadoc jest adresowany oddzielnie do wstawki 7, Javadoc.

każdy podział linii może być poprzedzony dowolnymi białymi znakami, po których następuje komentarz implementacyjny.Taki komentarz powoduje, że linia nie jest pusta.

4.8.6.1 styl komentowania bloków

komentarze bloków są wcięte na tym samym poziomie co otaczający je kod. Mogą być w/* ... */ style lub// ... style. W przypadku wielowierszowych komentarzy/* ... */ kolejne linie muszą zaczynać się od* wyrównanych z * w poprzedniej linii.

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

komentarze nie są zamknięte w polach oznaczonych gwiazdkami lub innymi znakami.

wskazówka: podczas pisania komentarzy wielowierszowych użyj stylu/* ... */, jeśli chcesz, aby automatyczne formatowanie kodu rozerwało linie w razie potrzeby (styl akapitowy). Większość formaterów nie zawija ponownie linii w blokach komentarzy stylu// ....

modyfikatory 4.8.7

modyfikatory klasy i członków, gdy są obecne, pojawiają się w zamówieniu zalecanym przez specyfikację języka Java:

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

4.8.8 liter numerycznych

longliterały całkowite używają wielkiej literyL sufiks, nigdy nie należy używać litery (aby uniknąć pomyłki z cyfrą1). Na przykład 3000000000Lzamiast 3000000000l.

5 nazewnictwo

5.1 zasady wspólne dla wszystkich identyfikatorów

używają tylko liter i cyfr ASCII, a w niewielkiej liczbie przypadków wymienionych poniżej podkreślenia. W ten sposób każdej poprawnej nazwie identyfikatora odpowiada Wyrażenie regularne\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.

nazwy klas są zazwyczaj rzeczownikami lub frazami rzeczownikowymi. Na przykładCharacter lubImmutableList. Nazwy interfejsów mogą być również rzeczownikami lub frazami (na przykład List), ale czasami mogą być zamiast nich przymiotnikami lub frazami przymiotnikowymi (na przykładReadable).

nie ma konkretnych reguł ani nawet ugruntowanych konwencji nazewnictwa typów adnotacji.

klasy testowe są nazwane zaczynając od nazwy klasy, którą testują, a kończąc na Test. Na przykładHashTest lubHashIntegrationTest.

5.2.3 nazwy metod

nazwy metod są zapisywane w małym formacie.

nazwy metod są zazwyczaj czasownikami lub zwrotami czasownikowymi. Na przykładsendMessage lubstop.

podkreślenia mogą pojawić się w nazwach JUnit test method, aby oddzielić logiczne komponenty thename, z każdym komponentem zapisanym w lowerCamelCase.Jednym z typowych wzorców jest <methodUnderTest>_<state>,na przykład pop_emptyStack. Nie ma jednego poprawnego sposobu na nazwanie metod badań.

5.2.4 nazwy stałych

nazwy stałych używająCONSTANT_CASE: wszystkie znaczniki wielkich liter, z każdym słowem oddzielonym od następnego pojedynczym znakiem podkreślenia. Ale czym właściwie jest stały?

stałe są statycznymi polami końcowymi, których zawartość jest głęboko niezmienna i których metody mają nodetectable skutki uboczne. Obejmuje to elementy podstawowe, ciągi znaków, niezmienne typy i niezmienne Kolekcje typów niezmiennych. Jeśli którekolwiek z obserwowalnych Stanów instancji może się zmienić, nie jest stałe. Samo zamierzanie nigdy nie zmutować obiektu nie wystarczy. Przykłady:

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

nazwy te są zazwyczaj rzeczownikami lub frazami rzeczownikowymi.

5.2.5 niestałe nazwy pól

niestałe nazwy pól (statyczne lub inne) zapisywane są w małej obudowie.

nazwy te są zazwyczaj rzeczownikami lub frazami rzeczownikowymi. Na przykładcomputedValues lubindex.

5.2.6 nazwy parametrów

nazwy parametrów są zapisywane w formacie lowerCamelCase.

należy unikać jednoznakowych nazw parametrów w metodach publicznych.

5.2.7 nazwy zmiennych lokalnych

nazwy zmiennych lokalnych są zapisywane w formacie lowerCamelCase.

nawet gdy zmienne końcowe i niezmienne, zmienne lokalne nie są uważane za stałe i nie powinny być stylizowane jako stałe.

5.2.8 nazwy zmiennych typu

każda zmienna typu jest nazwana w jednym z dwóch stylów:

• pojedyncza wielka litera, opcjonalnie po której następuje pojedyncza cyfra (taka jak ETXT2)
• nazwa w formie używanej dla klas (patrz sekcja 5.2.2, nazwy klas), po której następuje wielka litera T (przykłady: RequestTFooBarT).

5.3 przypadek wielbłąda: zdefiniowany

czasami istnieje więcej niż jeden rozsądny sposób na przekształcenie angielskiej frazy w przypadek wielbłąda,na przykład gdy występują akronimy lub nietypowe konstrukcje, takie jak „IPv6” lub „iOS”. Aby poprawić przewidywalność, styl Google określa następujący (prawie) deterministyczny schemat.

począwszy od formy prozy nazwy:

1. Konwertuj frazę na zwykły ASCII i usuń wszelkie apostrofy. Na przykład „algorytm Müllera „może stać się”algorytmem Muellera”.
2. podziel ten wynik na słowa, dzieląc na spacje i pozostałe znaki interpunkcyjne (zazwyczaj myślniki).
   • zalecane: jeśli jakiekolwiek słowo ma już konwencjonalny wygląd wielbłąda w powszechnym użyciu, Podziel to na jego części składowe (np. „AdWords” staje się „ad words”). Zauważ, że słowo takie jak „iOS” nie jest tak naprawdę w przypadku wielbłąda per se; wymyka się jakiejkolwiek konwencji, więc to zalecenie nie ma zastosowania.
3. teraz wszystko małymi literami (łącznie z akronimami), a następnie wielkimi literami tylko pierwszy znak:
   • … każde słowo, aby dać górny Wielbłąd lub
   • … każde słowo, z wyjątkiem pierwszego, daje dolną wielkość liter
4. wreszcie, połącz wszystkie słowa w jeden identyfikator.

zauważ, że obudowa oryginalnych słów jest prawie całkowicie pominięta. Przykłady:

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: zawsze używana

metoda jest oznaczona adnotacją @Override, gdy jest legalna. Obejmuje to metodę klasy nadpisującą metodę superklasową, metodę klasy implementującą metodę interfejsu oraz metodę interfejsu uwzględniającą metodę superinterfacemethod.

wyjątek:@Overridemożna pominąć, gdy metoda nadrzędna to @Deprecated.

6.2 Caught exceptions: not ignored

z wyjątkiem przypadków opisanych poniżej, bardzo rzadko jest poprawne nic nie robić w odpowiedzi na caughtexception. (Typowymi odpowiedziami jest zapisanie go, lub jeśli jest to uważane za” niemożliwe”, rethrow to jakoAssertionError.)

Kiedy naprawdę jest właściwe, aby nie podejmować żadnych działań w bloku catch, powód, dla którego jest to uzasadnione, jest wyjaśniony w komentarzu.

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

wyjątek: w testach przechwycony wyjątek może być ignorowany Bez komentarza, jeśli jego nazwa jest lub zaczyna się odexpected. Thefollowing jest bardzo powszechnym idiomem zapewniającym, że testowany kod wyrzuca wyjątek oczekiwanego typu, więc komentarz jest tutaj niepotrzebny.

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

6.3 statyczne elementy: kwalifikowane za pomocą klasy

gdy odwołanie do statycznego elementu klasy musi być kwalifikowane, jest kwalifikowane z nazwą tej klasy, a nie z odniesieniem lub wyrażeniem typu tej klasy.

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

6.4 Finalizery: nie używane

niezwykle rzadko można nadpisaćObject.finalize.

wskazówka: nie rób tego. Jeśli koniecznie musisz, najpierw Przeczytaj i zrozum Effective Java Punkt 7, „Avoid Finalizers”, bardzo ostrożnie, a potem nie rób tego.

7 Javadoc

7.1 formatowanie

7.1.1 ogólna forma

podstawowe formatowanie bloków Javadoc wygląda tak, jak w tym przykładzie:

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

… lub w tym jednoliniowym przykładzie:

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

podstawowa forma jest zawsze akceptowalna. Forma jednowierszowa może zostać zastąpiona, gdy całość bloku Javadoc (w tym znaczniki komentarzy) zmieści się w jednej linii. Zauważ, że dotyczy to tylko wtedy, gdy nie ma znaczników bloków, takich jak @return.

7.1.2 akapity

jedna pusta linia—to znaczy linia zawierająca tylko wyrównaną gwiazdkę wiodącą (*)—pojawia się między akapitami, a przed grupą znaczników blokowych ifpresent. Każdy akapit, ale pierwszy ma<p> bezpośrednio przed pierwszym słowem,bez spacji po.

7.1.3 znaczniki bloków

dowolny ze standardowych „znaczników bloków”, które są używane, pojawia się w kolejności@param@return@throws@deprecated, a te cztery typy nigdy nie występują z pustym opisem. Jeśli znacznik bloku nie mieści się w jednej linii, linie kontynuujące mają wcięte cztery (lub więcej) spacje z pozycji @.

7.2 fragment podsumowania

każdy blok Javadoc zaczyna się od krótkiego fragmentu podsumowania. Thisfragment jest bardzo ważny: jest to jedyna część tekstu, która pojawia się w pewnych kontekstach, takich jak indeksy klasy i metod.

jest to fragment—fraza rzeczownikowa lub czasownikowa, a nie pełne zdanie. Nie zaczyna się od A {@code Foo} is a... lubThis method returns..., ani nie tworzy pełnego przesłania imperatywnego Save the record.. Jednak fragment jest pisany wielką literą ipunktowany tak, jakby był pełnym zdaniem.

Wskazówka: częstym błędem jest zapisanie prostego Javadoc w formie/** @return the customer ID */. Jest to niepoprawne i powinno zostać zmienione na /** Returns the customer ID. */.

7.3 Gdzie Javadoc jest używany

co najmniej, Javadoc jest obecny dla każdegopublic klasy i każdegopublic lubprotected członka takiej klasy, z kilkoma wyjątkami podanymi poniżej.

może być również dostępna Dodatkowa zawartość Javadoc, jak wyjaśniono w sekcji 7.3.4,niewymagająca Javadoc.

7.3.1 Exception: self-explanatory methods

Javadoc jest opcjonalny dla „prostych, oczywistych” metod, takich jakgetFoo, w przypadkach, gdy naprawdę i naprawdę nie ma nic innego wartego powiedzenia, ale „zwraca foo”.

ważne: nie jest właściwe powoływanie się na ten wyjątek, aby uzasadnić podanie istotnych informacji, które typowy czytelnik może potrzebować znać. Na przykład, dla metody o nazwie getCanonicalName, nie pomijaj jej dokumentacji(z uzasadnieniem, że mówi tylko/** Returns the canonical name. */), jeśli typowy czytelnik może nie mieć pomysłu, co oznacza termin „nazwa kanoniczna”!

7.3.2 wyjątek: przesłania

Javadoc nie zawsze występuje w metodzie, która nadpisuje metodę supertype.

7.3.4 Niewymagany Javadoc

Inne klasy i członkowie mają Javadoc w zależności od potrzeb lub potrzeb.