1 Introducere

acest document servește ca o definiție completă a standardelor de codificare Google pentrucodul sursă în limbajul de programare Java. Un fișier sursă Java este descris ca fiind inGoogle stil dacă și numai dacă aderă la regulile de aici.

ca și alte ghiduri de stil de programare, problemele acoperite se întind nu numai pe probleme estetice de formatare, ci și pe alte tipuri de convenții sau standarde de codificare. Cu toate acestea, acest document se concentrează în primul rând pe regulile dure și rapide pe care le urmăm universal și nu oferă sfaturi care nu sunt în mod clar aplicabile (fie prin om, fie prin instrument).

1.1 terminologie note

în acest document, dacă nu se clarifică altfel:

1. termenul clasă este folosit inclusiv pentru a însemna o clasă „obișnuită”, o clasă enum, o interfață sau un tip de adnotare (@interface).
2. termenul membru (al unei clase) este folosit inclusiv pentru a însemna o clasă imbricată, câmp, metodă sau constructor; adică, toate conținuturile de nivel superior ale unei clase, cu excepția inițializatorilor și comentariilor.
3. termenul comentariu se referă întotdeauna la comentarii de implementare. Nu folosim expresia „comentarii de documentare”, ci folosim termenul comun ” Javadoc.”

alte” note terminologice ” vor apărea ocazional pe tot parcursul documentului.

1.2 ghid note

exemplu de cod în acest document este non-normativ. Adică, în timp ce exemplelesunt în stil Google, este posibil să nu ilustreze singurul mod elegant de a reprezentacodul. Opțiunile de formatare opționale făcute în exemple nu ar trebui aplicate ca reguli.

2 bazele fișierului sursă

2.1 Nume fișier

numele fișierului sursă este format din numele sensibil la majuscule al clasei de nivel superior pe care o conține(din care există exact unul), plus extensia.java.

2.2 codare fișier: UTF-8

fișierele sursă sunt codificate în UTF-8.

2.3 caractere speciale

2.3.1 caractere de spațiu alb

în afară de secvența Terminatorului de linie, ASCII horizontal spacecharacter (0x20) este singurul caracter de spațiu alb care apare oriunde într-un fișier sursă. Aceasta implică faptul că:

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

2.3.3 caractere non-ASCII

pentru caracterele non-ASCII rămase, se utilizează fie caracterul Unicode real(de exemplu,∞), fie echivalentul Unicode escape(de exemplu,\u221e). Alegerea depinde doar deceea ce face Codul mai ușor de citit și de înțeles, deși Unicode evadeazăîn afara literalelor și comentariilor șirurilor sunt puternic descurajate.

Sfat: În cazul Unicode escape și, ocazional, chiar și atunci când sunt utilizate caractere actualUnicode, un comentariu explicativ poate fi foarte util.

Exemple:

exemplu	discuție
String unitAbbrev = "μs";	cel mai bun: perfect clar chiar și fără un comentariu.
String unitAbbrev = "\u03bcs"; // "μs"	permis, dar nu există niciun motiv pentru a face acest lucru.
String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"	permis, dar incomod și predispus la greșeli.
String unitAbbrev = "\u03bcs";	Poor: cititorul nu are nici o idee despre ce este.
return '\ufeff' + content; // byte order mark	bun: utilizați escapes pentru caractere neimprimabile și comentați dacă este necesar.

sfat: nu face Codul mai puțin ușor de citit pur și simplu de teamă că unele programe s-ar putea să nu se ocupe de caractere non-ASCII în mod corespunzător. Dacă acest lucru ar trebui să se întâmple, aceștiaprogramele sunt rupte și trebuie reparate.

3 structura fișierului sursă

exact o linie goală separă fiecare secțiune care este prezent.

3.1 informații despre licență sau drepturi de autor, dacă sunt prezente

dacă informațiile despre licență sau drepturi de autor aparțin unui fișier, acestea aparțin aici.

3.2 instrucțiunea pachetului

instrucțiunea pachetului nu este înfășurată în linie. Limita coloanei (secțiunea 4.4,limita coloanei: 100) nu se aplică declarațiilor pachetului.

3.3 declarații de Import

3.3.1 nu sunt utilizate importuri wildcard

importuri Wildcard, statice sau de altă natură.

3.3.2 no line-wrapping

declarațiile de Import nu sunt line-wrapped. Limita coloanei (secțiunea 4.4,limita coloanei: 100) nu se aplică declarațiilor de import.

3.3.3 ordonarea și spațierea

importurile sunt ordonate după cum urmează:

1. toate importurile statice într-un singur bloc.
2. toate importurile non-statice într-un singur bloc.

dacă există atât importuri statice, cât și non-statice, o singură linie goală separă cele două blocuri. Nu există alte linii goale între declarațiile de import.

în fiecare bloc numele importate apar în ordine de sortare ASCII. (Notă: Acest lucru nu este același lucru cu declarațiile de import fiind în ordine de sortare ASCII, deoarece ‘.’sortează înainte’;’.)

3.3.4 Niciun import static pentru clasele

importul Static nu este utilizat pentru clasele imbricate statice. Acestea sunt importate cuimporturi normale.

3.4 declarație de clasă

3.4.1 exact o declarație de clasă de nivel superior

fiecare clasă de nivel superior se află într-un fișier sursă propriu.

3.4.2 ordonarea conținutului clasei

ordinea pe care o alegeți pentru membrii și inițializatorii clasei dvs. poate avea un efect deosebit asupralarnabilitate. Cu toate acestea, nu există o singură rețetă corectă pentru cum să o faceți; diferite clase își pot ordona conținutul în moduri diferite.

ceea ce este important este că fiecare clasă folosește o anumită ordine logică, pe care itsmainer ar putea explica dacă i se cere. De exemplu, noile metode nu sunt adăugate doar în mod obișnuit la sfârșitul clasei, deoarece aceasta ar produce ordonarea „cronologică după data adăugată”, ceea ce nu este o comandă logică.

3.4.2.1 suprasarcini: niciodată divizat

atunci când o clasă are mai mulți constructori, sau mai multe metode cu același nume, acestea aparsequential, cu nici un alt cod între (nici măcar membri privați).

4 formatare

terminologie notă: constructul de tip bloc se referă lacorpul unei clase, metode sau Constructori. Rețineți că, prin secțiunea 4.8.3.1 inițializatoare onarray, orice inițializator de matrice poate fi tratat opțional ca și cum ar fi un construct asemănător unui bloc.

4.1 Bretele

4.1.1 acolade sunt utilizate în cazul în care opțional

acolade sunt utilizate cuifelsefordo șiwhile declarații, chiar și atunci când thebody este gol sau conține doar o singură declarație.

4.1.2 blocuri nepoluante: k& stil R

acolade urmează stilul Kernighan și Ritchie(„paranteze Egiptene”)pentru blocuri nepoluante și construcții asemănătoare blocurilor:

• nicio întrerupere de linie înainte de breteaua de deschidere.
• pauză de linie după bretele de deschidere.
• pauză de linie înainte de bretele de închidere.
• pauză de linie după brace de închidere, numai în cazul în care brace se termină o declarație sau se termină corpul unei metode, constructor, sau clasa numit. De exemplu, nu există nicio pauză de linie după bretele dacă este urmată de else sau o virgulă.

Exemple:

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

câteva excepții pentru clasele enum sunt date în secțiunea 4.8.1,clasele Enum.

4.1.3 blocuri goale: poate fi concis

un bloc gol sau un construct asemănător unui bloc poate fi în K& stil R (așa cum este descris în secțiunea 4.1.2). Alternativ, poate fi închis imediat după deschidere, fără caractere sau întreruperi între ele({}), cu excepția cazului în care face parte din Instrucțiunea amulti-block (una care conține direct mai multe blocuri:if/else sautry/catch/finally).

Exemple:

 // 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 indentare bloc: + 2 spații

de fiecare dată când se deschide un bloc nou sau o construcție asemănătoare unui bloc, liniuța crește cu douăspații. Când blocul se termină, liniuța revine la nivelul anterior al liniuței. Nivelul liniuțiise aplică atât codului, cât și comentariilor din întregul bloc. (A se vedea exemplul din secțiunea 4.1.2,blocuri nepoluante: K & R Style.)

4.3 o declarație pe linie

fiecare declarație este urmată de o întrerupere de linie.

4.4 limita coloanei: 100

codul Java are o limită de coloană de 100 de caractere. Un „caracter” înseamnă orice punct de cod Unicode.Cu excepția celor menționate mai jos, orice linie care ar depăși această limită trebuie să fie înfășurată în linie, așa cum se explică în secțiunea 4.5, înfășurarea în linie.

fiecare punct de cod Unicode contează ca un caracter, chiar dacă lățimea sa de afișare este mai mare sau mai mică. De exemplu,dacă utilizațicaractere lățime completă, puteți alege să înfășurați linia mai devreme decât în cazul în care această regulă necesită strict.

excepții:

1. linii în care respectarea limitei coloanei nu este posibilă (de exemplu, un URL lung în Javadoc sau o referință lungă a metodei jsni).
2. package șiimport declarații (a se vedea secțiunile 3.2 declarație pachet și 3.3 declarații de Import).
3. linii de comandă într-un comentariu care poate fi tăiat și lipit într-un shell.

4.5 line-wrapping

terminologie notă: când codul care altfel ar putea ocupa legal o singură linie este împărțit în mai multe linii, această activitate se numește line-wrapping.

nu există o formulă cuprinzătoare, deterministă care să arate exact cum să se înfășoare în fiecare situație. Foarte des există mai multe modalități valide de a înfășura aceeași bucată de cod.

notă: în timp ce motivul tipic pentru linia de ambalaj este de a evitafluxul limita de coloană, chiar și codul care s-ar potrivi, de fapt, în limita de coloană poate linie înfășurat la discreția autorului.

sfat: extragerea unei metode sau a unei variabile locale poate rezolva problemafără a fi nevoie să înfășurați linia.

4.5.1 unde se rupe

prima directivă a înfășurării liniei este: preferă ruperea la un nivel sintactic superior. De asemenea:

1. când o linie este întreruptă la un operator care nu este atribuit, pauza vine înaintea simbolului. (Rețineți că aceasta nu este aceeași practică utilizată în stilul Google pentru alte limbi, cum ar fi C++ și JavaScript.)
   • acest lucru se aplică și următoarelor simboluri „asemănătoare operatorului”:
     • separatorul de puncte (.)
     • cele două puncte ale unei metode de referință (::)
     • un ampersand într-un tip legat (<T extends Foo & Bar>)
     • o țeavă într-un bloc de captură (catch (FooException | BarException e)).
2. când o linie este întreruptă la un operator de atribuire, pauza vine de obicei după simbol, dar oricum este acceptabilă.
   • acest lucru se aplică și colonului „cesiune-operator-like” dintr-o instrucțiune îmbunătățităfor („foreach”).
3. o metodă sau un nume de constructor rămâne atașat la paranteza deschisă (() care o urmează.
4. o virgulă (,) rămâne atașată la tokenul care o precede.
5. o linie nu este niciodată ruptă adiacentă săgeții dintr-o lambda, cu excepția faptului că o pauză poate veni imediat după săgeată dacă corpul lambda constă dintr-o singură expresie fără margini. Exemple:

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

notă: scopul principal pentru înfășurarea liniei este de a avea un cod clar, nu neapărat un cod care se potrivește cu cel mai mic număr de linii.

4.5.2 linii de continuare a liniuței cel puțin +4 spații

la înfășurarea liniei, fiecare linie după prima (fiecare linie de continuare) este indentată cel puțin +4 față de linia inițială.

când există mai multe linii de continuare, indentarea poate varia dincolo de +4 așa cum se dorește. În general, două linii de continuare utilizează același nivel de indentare dacă și numai dacă acesteaîncepeți cu elemente sintactic paralele.secțiunea 4.6.3 privind alinierea orizontală abordează practica descurajată de a folosi un număr variabil de spații pentru a alinia anumite jetoane cu liniile anterioare.

4.6 spațiu alb

4.6.1 spațiu alb Vertical

apare întotdeauna o singură linie goală:

1. între membrii consecutivi sau inițializatorii unei clase: câmpuri, Constructori, metode, clase imbricate, inițializatoare statice și inițializatoare de instanță.
   • excepție: o linie goală între două câmpuri consecutive (fără alt cod între ele) este opțională. Astfel de linii goale sunt utilizate după cum este necesar pentru a crea grupări logice de câmpuri.
   • excepție: liniile goale dintre constantele enum sunt acoperite în secțiunea 4.8.1.
2. conform cerințelor altor secțiuni ale acestui document (cum ar fi Secțiunea 3, structura fișierului sursă și secțiunea 3.3, declarații de Import).

o singură linie goală poate apărea, de asemenea, oriunde îmbunătățește lizibilitatea, de exemplu between statements pentru a organiza codul în subsecțiuni logice. O linie goală înainte de primul membru orinitializer, sau după ultimul membru sau inițializator al clasei, nu este încurajată nordiscouraged.

sunt permise mai multe linii goale consecutive, dar niciodată necesare (sau încurajate).

4.6.2 spațiu alb orizontal

dincolo de unde este cerut de limbă sau alte reguli de stil și, în afară de literali, comentarii șijavadoc, un singur spațiu ASCII apare și în următoarele locuri.

1. separarea oricărui cuvânt rezervat, cum ar fi iffor sau catch, dintr-o paranteză deschisă (() care îl urmează pe acea linie
2. separând orice cuvânt rezervat, cum ar fi else sau catch, de o proteză ondulată de închidere (}) care o precede pe acea linie
3. înainte de orice proteză ondulată deschisă ({), cu două excepții:
   • @SomeAnnotation({a, b}) (nu se folosește spațiu)
   • String x = {{"foo"}}; (nu este necesar spațiu între{{, după articolul 8 de mai jos)
4. pe ambele părți ale oricărui operator binar sau ternar. Acest lucru este valabil și pentru următoarele simboluri „asemănătoare operatorului”:
   • ampersandul într-un tip conjunctiv legat: <T extends Foo & Bar>
   • conducta pentru un bloc de captură care gestionează mai multe excepții: catch (FooException | BarException e)
   • colon (:) într-o enhanced for („foreach”) declarație
   • săgeata într-o expresie lambda: (String str) -> str.length()

   dar nu

   • cele două puncte (::) ale unei metode de referință, care este scrisă ca Object::toString
   • separatorul de puncte (.), care este scris ca object.toString()
5. după ,:; sau paranteza de închidere ()) a unei distribuții
6. pe ambele părți ale barei duble (//) care începe un comentariu la sfârșitul liniei. Aici sunt permise mai multe spații, dar nu sunt necesare.
7. între tipul și variabila unei declarații:List<String> list
8. opțional doar în interiorul ambelor bretele ale unui inițializator de matrice
   • new int {5, 6} șinew int { 5, 6 } sunt ambele valide
9. între o adnotare de tip și sau....

această regulă nu este interpretată niciodată ca necesitând sau interzicând spațiu suplimentar la începutul sau la sfârșitul unei linii; se adresează numai spațiului interior.

4.6.3 aliniere orizontală: niciodată necesară

terminologie notă: Alinierea orizontală estepractica de a adăuga un număr variabil de spații suplimentare în codul dvs. cu scopul de a faceanumite jetoane apar direct sub anumite alte jetoane de pe liniile anterioare.

această practică este permisă, dar nu este niciodată cerută de Google Style. Nu estechiar necesar să se mențină alinierea orizontală în locurile în care a fost deja utilizată.

iată un exemplu fără aliniere, apoi folosind alinierea:

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

sfat: alinierea poate ajuta la lizibilitate, dar creează probleme pentru întreținerea viitoare. Luați în considerare o schimbare viitoare care trebuie să atingă o singură linie. Această modificare poatelăsați formatarea plăcută anterior mutilată și acest lucru este permis. Cel mai adeseaAcesta solicită coder (poate tu) pentru a regla spațiul alb pe liniile din apropiere, de asemenea, posibiltriggering o serie în cascadă de reformatări. Această schimbare de o singură linie are acum o ” rază de explozie.”Acest lucru poate duce în cel mai rău caz la o muncă inutilă, dar, în cel mai bun caz, corupe în continuare istoricul versiunilorinformații, încetinește recenzenții și exacerbează conflictele de îmbinare.

4.7 gruparea parantezelor: recomandat

parantezele de grupare opționale sunt omise numai atunci când autorul și recenzorul sunt de acord că nu există nicio șansă rezonabilă ca Codul să fie interpretat greșit fără ele și nici nu ar fi făcut Codul mai ușor de citit. Nu este rezonabil să presupunem că fiecare cititor are memorat întregul tabel de prioritate Javaoperator.

4.8 constructe specifice

4.8.1 clase Enum

după fiecare virgulă care urmează unei constante enum, o întrerupere de linie este opțională. De asemenea, sunt permise linii goale suplimentare (de obicei doar una). Aceasta este o posibilitate:

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

o clasă enum fără metode și fără documentație privind constantele sale poate fi formată opțional ca și cum ar fi un inițializator de matrice (vezi secțiunea 4.8.3.1 inițializatoare onarray).

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

deoarece clasele enum sunt clase, se aplică toate celelalte reguli pentru formatarea claselor.

4.8.2 declarații variabile

4.8.2.1 o variabilă pe declarație

fiecare declarație variabilă (câmp sau local) declară o singură variabilă: declarații precumint a, b; nu sunt utilizate.

excepție: Declarațiile variabile Multiple sunt acceptabile în antetul uneifor buclă.

4.8.2.2 declarate atunci când este necesar

variabilele locale nu sunt declarate în mod obișnuit la începutul blocului lor de conținut sau al construcției de tip bloc. În schimb, variabilele locale sunt declarate aproape de punctul în care sunt utilizate pentru prima dată (în rațiune), pentru a minimiza domeniul lor de aplicare. Declarațiile variabile locale au de obiceiinițializatori sau sunt inițializați imediat după declarație.

4.8.3 matrice

4.8.3.1 inițializatoare matrice: poate fi „block-like „

orice inițializator matrice poate fi opțional formatat ca și cum ar fi un ” Block-likeconstruct.”De exemplu, următoarele sunt valide (nu o listă exhaustivă):

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 nu există declarații de matrice în stil C

parantezele pătrate formează o parte a tipului, nu variabila:String args, nuString args.

4.8.4 declarații comutator

terminologie notă: în interiorul acolade de bloc aswitch sunt una sau mai multe grupuri de declarație. Fiecare grup de instrucțiuni este format dinuna sau mai multe etichete de comutare (fie case FOO: saudefault:), urmate de una sau mai multe instrucțiuni (sau, pentru ultimul grup de instrucțiuni, zero sau mai multe instrucțiuni).

4.8.4.1 indentare

ca în cazul oricărui alt bloc, conținutul unui bloc de comutare este indentat +2.

după o etichetă de comutare, există o pauză de linie, iar nivelul de indentare este crescut +2, exact ca și cum un bloc ar fi deschis. Următoarea etichetă de comutare revine la liniuța anterioarănivel, ca și cum un bloc ar fi fost închis.

4.8.4.2 cădere: comentate

într-un bloc de comutare, fiecare grup declarație fie se termină brusc (cu unbreakcontinuereturn sau aruncat excepție), sau este marcat cu un commentto indică faptul că executarea va sau ar putea continua în următorul grup declarație. Anycomment care comunică ideea de cădere este suficientă (de obicei// fall through). Acest comentariu special nu este necesar înUltimul grup de instrucțiuni al blocului de comutare. Exemplu:

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

observați că nu este nevoie de niciun comentariu dupăcase 1:, doar la sfârșitul grupului de instrucțiuni.

4.8.4.3default cazul este prezent

fiecare instrucțiune de comutare include undefault statementgroup, chiar dacă nu conține cod.

excepție: o instrucțiune de comutare pentru un tipenum poate omite grupul de instrucțiunidefault, dacă include cazuri implicite care acoperă toate valorile posibile ale acelui tip. Acest lucru permite IDE sau alte instrumente de analiză statică să emită un avertisment dacă au fost pierdute cazuri.

4.8.5 adnotările

adnotările care se aplică unei clase, unei metode sau unui constructor apar imediat după blocul de documente și fiecare adnotare este listată pe o linie proprie (adică o adnotare pe linie). Aceste pauze de linie nu constituie înfășurare de linie (secțiunea 4.5, înfășurare de linie), astfel încât nivelul de indentare nu este crescut. Exemplu:

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

excepție: O singură adnotare fără parametri poate apărea în schimb împreună cu prima linie a semnăturii, de exemplu:

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

adnotările care se aplică unui câmp apar și imediat după blocul de documentație, dar în acest caz, mai multe adnotări (posibil parametrizate) pot fi listate pe aceeași linie;de exemplu:

@Partial @Mock DataLoader loader;

pentru formatarea adnotărilor pe parametri, variabile locale sau tipuri.

această secțiune abordează comentariile privind implementarea. Javadoc se adresează separat însecțiunea 7, Javadoc.

orice întrerupere de linie poate fi precedată de un spațiu alb arbitrar urmat de un comentariu de implementare.Un astfel de comentariu face ca linia să nu fie goală.

4.8.6.1 stil comentariu bloc

comentariile bloc sunt indentate la același nivel cu codul din jur. Ele pot fi în /* ... */ stil sau// ... stil. Pentru mai multe linii/* ... */ comentarii, liniile ulterioare trebuie să înceapă cu* aliniate cu * pe linia anterioară.

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

comentariile nu sunt închise în cutii desenate cu asteriscuri sau alte caractere.

sfat: Când scrieți comentarii cu mai multe linii, utilizați/* ... */ stil dacă doriți ca formatatoarele automate de cod să rupă liniile atunci când este necesar (stil paragraf). Majoritatea formatorilor nu re-înfășoară linii în// ... blocuri de comentarii în stil.

4.8.7 modificatorii

modificatorii de clasă și membri, atunci când sunt prezenți, apar în orderrecomandat de specificația limbajului Java:

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

4.8.8 literali numerici

long-literalii întregi valorificați folosesc un majusculăL sufix, neverlowercase (pentru a evita confuzia cu cifra1). De exemplu, 3000000000Lmai degrabă decât 3000000000l.

5 denumirea

5.1 reguli comune tuturor identificatorilor

identificatorii folosesc doar litere și cifre ASCII și, într-un număr mic de cazuri menționate mai jos, sublinieri. Astfel, fiecare nume de identificator valid este asociat cu expresia regulată \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.

numele clasei sunt de obicei substantive sau fraze substantive. De exemplu,Character sauImmutableList. Numele de interfață pot fi, de asemenea, substantive saufraze substantive (de exemplu, List), dar uneori pot fiadjective sau fraze adjective în schimb (de exemplu,Readable).

nu există reguli specifice sau chiar convenții bine stabilite pentru denumirea tipurilor de adnotări.

clasele de testare sunt denumite începând cu numele clasei pe care o testează și terminând cuTest. De exemplu,HashTest sauHashIntegrationTest.

5.2.3 numele metodelor

numele metodelor sunt scrise în lowerCamelCase.

numele metodei sunt de obicei verbe sau fraze verbale. De exemplu,sendMessage saustop.

sublinierile pot apărea în numele metodelor de testare JUnit pentru a separa componentele logice ale numelui, fiecare componentă fiind scrisă în lowerCamelCase.Un model tipic este<methodUnderTest>_<state>,de exemplupop_emptyStack. Nu există nimeni Corectmod de a numi metode de testare.

5.2.4 nume constante

numele constante folosescCONSTANT_CASE: toate literele superioare, fiecare cuvânt fiind separat de următorul printr-o singură subliniere. Dar ce este aconstant, mai exact?

constantele sunt câmpuri finale statice al căror conținut este profund imuabil și ale căror metode au efecte secundare nodetectabile. Aceasta include primitive, șiruri, tipuri imuabile și colecții imuabile de tipuri imuabile. Dacă oricare dintre starea observabilă a instanței se poate schimba, nu este aconstantă. Doar intenția de a nu muta niciodată obiectul nu este suficientă. Exemple:

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

aceste nume sunt de obicei substantive sau fraze substantive.

5.2.5 numele câmpurilor neconstante

numele câmpurilor neconstante (statice sau de altă natură) sunt scrise în camera inferioară.

aceste nume sunt de obicei substantive sau fraze substantive. De exemplu,computedValues sauindex.

5.2.6 numele parametrilor

numele parametrilor sunt scrise în lowerCamelCase.

numele parametrilor cu un caracter din metodele publice trebuie evitate.

5.2.7 numele variabilelor locale

numele variabilelor locale sunt scrise în lowerCamelCase.

chiar și atunci când sunt finale și imuabile, variabilele locale nu sunt considerate constante și nu ar trebui să fie denumite constante.

5.2.8 nume de variabile de tip

fiecare variabilă de tip este denumită într-unul din cele două stiluri:

• o singură majusculă, urmată opțional de un singur număr (cum ar fi ETXT2)
• un nume în forma utilizată pentru clase (a se vedea secțiunea 5.2.2, nume de clase), urmat de majusculă T (exemple: RequestTFooBarT).

5.3 Camel case: definit

uneori există mai multe modalități rezonabile de a converti o frază engleză în Camel case,cum ar fi atunci când sunt prezente acronime sau construcții neobișnuite precum „IPv6” sau „iOS”. Pentru a îmbunătățiprevizibilitate, Google Style specifică următoarea schemă (aproape) deterministă.

începând cu forma de proză a numelui:

1. convertiți fraza în ASCII simplu și eliminați orice apostrof. De exemplu,” algoritmul lui M Okticller „ar putea deveni”algoritmul lui Muellers”.
2. împărțiți acest rezultat în cuvinte, împărțind spațiile și orice punctuație rămasă (de obicei cratime).
   • recomandat: dacă orice cuvânt are deja un aspect convențional de cămilă în uz comun, împărțiți-l în părțile sale constitutive (de exemplu, „AdWords” devine „cuvinte publicitare”). Rețineți că un cuvânt precum „iOS” nu este într-adevăr în caz de cămilă în sine; sfidează orice convenție, deci această recomandare nu se aplică.
3. acum totul minuscule (inclusiv acronime), apoi majuscule doar primul caracter al:
   • … fiecare cuvânt, pentru a obține caz cămilă superioară, sau
   • … fiecare cuvânt, cu excepția primului, pentru a obține caz cămilă mai mic
4. În cele din urmă, se alăture toate cuvintele într-un singur identificator.

rețineți că carcasa cuvintelor originale este aproape în întregime ignorată. Exemple:

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: folosit întotdeauna

o metodă este marcată cu@Override adnotarecând este legal. Aceasta include o metodă de clasă care înlocuiește o metodă superclasă, o metodă de clasă care implementează o metodă de interfață și o metodă de interfață care respectă o metodă superinterfacem.

excepție:@Override poate fi omisă atunci când metoda părinte este@Deprecated.

6.2 excepții capturate: nu sunt ignorate

cu excepția celor menționate mai jos, este foarte rar corect să nu faci nimic ca răspuns la o caughtexception. (Răspunsurile tipice sunt să-l conectați sau, dacă este considerat „imposibil”, să-l regândiți caAssertionError.)

când este cu adevărat potrivit să nu se ia nicio măsură într-un bloc de captură, motivul pentru care acest lucru este justificat este explicat într-un comentariu.

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

excepție: în teste, o excepție capturată poate fi ignorată fără comentarii dacă numele său este sau începe cuexpected. Următorul este un idiom foarte comun pentru a se asigura că codul testat aruncă o excepție de tipul așteptat, deci un comentariu nu este necesar aici.

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

6.3 membri statici: calificați folosind clasa

când o referință la un membru static al clasei trebuie să fie calificată, este calificată cu numele clasei respective, nu cu o referință sau o expresie a tipului clasei respective.

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

6.4 Finalizatoare: neutilizat

este extrem de rar să înlocuițiObject.finalize.

sfat: nu o face. Dacă trebuie absolut, citiți mai întâi și înțelegeți elementul Java eficient 7,”evitați Finalizatorii”, foarte atent și apoi nu o faceți.

7 Javadoc

7.1 formatare

7.1.1 forma generală

formatarea de bază a blocurilor Javadoc este așa cum se vede în acest exemplu:

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

… sau în acest exemplu cu o singură linie:

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

forma de bază este întotdeauna acceptabilă. Formularul cu o singură linie poate fi înlocuit atunci când întregul bloc Javadoc (inclusiv markerii de comentarii) se poate încadra pe o singură linie. Rețineți că acest lucru se aplică numai atunci când nu există etichete de blocare, cum ar fi @return.

7.1.2 paragrafe

o linie goală—adică o linie care conține doar asteriscul principal aliniat (*)—apare între paragrafe și înainte de grupul de etichete de bloc ifpresent. Fiecare paragraf, dar primul are <p> imediat înainte de primul cuvânt,fără spațiu după.

7.1.3 etichete de blocare

oricare dintre „etichetele de blocare” standard care sunt utilizate apar în ordinea @param@return@throws@deprecated, iar aceste patru tipuri nu apar niciodată cu o descriere goală. Când o etichetă de bloc nu se potrivește pe o singură linie, liniile de continuaresunt indentate patru (sau mai multe) spații din poziția @.

7.2 fragmentul rezumat

fiecare bloc Javadoc începe cu un fragment rezumat scurt. Acestfragment este foarte important: este singura parte a textului care apare în anumite contexte, cum ar ficlasa și indici de metodă.

acesta este un fragment—o frază substantivală sau o frază verbală, nu o propoziție completă. Ea doesnot începe cu A {@code Foo} is a..., sauThis method returns..., nici nu formează o sentencelike imperativ complet Save the record.. Cu toate acestea, fragmentul este scris cu majuscule șipunctuat ca și cum ar fi o propoziție completă.

sfat: o greșeală obișnuită este să scrieți Javadoc simplu sub forma/** @return the customer ID */. Acest lucru este incorect și ar trebui să fieschimbat la /** Returns the customer ID. */.

7.3 În cazul în care Javadoc este utilizat

la minim, Javadoc este prezent pentru fiecarepublicclasă și pentru fiecarepublicsauprotected membru al unei astfel de clase, cu câteva excepții menționate mai jos.

conținutul Javadoc suplimentar poate fi, de asemenea,prezent, după cum se explică în secțiunea 7.3.4, Javadoc neimpozabil.

7.3.1 excepție: metode auto-explicative

Javadoc este opțional pentru metode „simple, evidente” precumgetFoo, în cazurile în care nu există cu adevărat și cu adevărat altceva care merită spus decât „returnează foo”.

Important: nu este oportun să se menționeze această excepție pentru a justifica informațiile relevante pe care un cititor tipic ar putea avea nevoie să le cunoască. De exemplu, pentru o metodănumit getCanonicalName, nu omiteți documentația sa(cu rațiunea că ar spune doar/** Returns the canonical name. */) dacă un cititor tipic poate să nu aibă ideece înseamnă termenul” nume canonic”!

7.3.2 excepție: suprascrie

Javadoc nu este întotdeauna prezent pe o metodă care suprascrie o metodă supertip.

7.3.4 Javadoc neimpozabil

alte clase și membri au Javadoc după cum este necesar sau dorit.