1 Einführung

Dieses Dokument dient als vollständige Definition der Codierungsstandards von Google für Quellcode in der Programmiersprache Java™. Eine Java-Quelldatei wird genau dann als inGoogle-Stil beschrieben, wenn sie den hierin enthaltenen Regeln entspricht.

Wie andere Programmier-Styleguides umfassen die behandelten Themen nicht nur ästhetische Fragen der Formatierung, sondern auch andere Arten von Konventionen oder Codierungsstandards. Dieses Dokument konzentriert sich jedoch in erster Linie auf die festen Regeln, die wir allgemein befolgen, undvermeidet Ratschläge, die nicht eindeutig durchsetzbar sind (sei es durch Menschen oder Werkzeuge).

1.1 Hinweise zur Terminologie

In diesem Dokument, sofern nicht anders angegeben:

1. Der Begriff Klasse wird inklusiv verwendet, um eine „gewöhnliche“ Klasse, Enum-Klasse, Schnittstelle oder Annotationstyp zu bezeichnen (@interface).
2. Der Begriff member (einer Klasse) wird inklusiv verwendet, um eine verschachtelte Klasse, ein verschachteltes Feld, eine verschachtelte Methode oder einen verschachtelten Konstruktor zu bezeichnen; das heißt, alle Inhalte der obersten Ebene einer Klasse mit Ausnahme von Initialisierern und Kommentaren.
3. Der Begriff comment bezieht sich immer auf Implementierungskommentare. Wir verwenden nicht den Ausdruck „Dokumentationskommentare“, sondern den gebräuchlichen Begriff „Javadoc.“

Andere „Terminologiehinweise“ werden gelegentlich im gesamten Dokument angezeigt.

1.2 Hinweise zur Anleitung

Der Beispielcode in diesem Dokument ist nicht normativ. Das heißt, während die Beispiele im Google-Stil sind, veranschaulichen sie möglicherweise nicht die einzige stilvolle Art, den Code darzustellen. Optionale Formatierungsoptionen in Beispielen sollten nicht als Regeln erzwungen werden.

2 Grundlagen der Quelldatei

2.1 Dateiname

Der Name der Quelldatei besteht aus dem Namen der obersten Klasse (von der es genau eine gibt) und der Erweiterung.java.

2.2 Dateikodierung: UTF-8

Quelldateien werden in UTF-8 kodiert.

2.3 Sonderzeichen

2.3.1 Leerzeichen

Abgesehen von der Zeilenabschlussfolge ist das ASCII-Leerzeichen (0x20) das einzige Leerzeichen, das irgendwo in einer Quelldatei vorkommt. Dies impliziert, dass:

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

2.3.3 Nicht-ASCII-Zeichen

Für die verbleibenden Nicht-ASCII-Zeichen wird entweder das eigentliche Unicode-Zeichen(z. B. ∞) oder das äquivalente Unicode-Escape-Zeichen(z. B. \u221e) verwendet. Die Wahl hängt nur davon ab, was den Code leichter zu lesen und zu verstehen macht, obwohl Unicode-Escapesaußerhalb von String-Literalen und Kommentaren dringend abgeraten wird.

Tipp: Im Unicode-Escape-Fall und gelegentlich auch dann, wenn actualUnicode-Zeichen verwendet werden, kann ein erläuternder Kommentar sehr hilfreich sein.

Beispiele:

Beispiel	Diskussion
String unitAbbrev = "μs";	Am besten: auch ohne Kommentar vollkommen klar.
String unitAbbrev = "\u03bcs"; // "μs"	Erlaubt, aber es gibt keinen Grund, dies zu tun.
String unitAbbrev = "\u03bcs"; // Greek letter mu, "s"	Erlaubt, aber umständlich und fehleranfällig.
String unitAbbrev = "\u03bcs";	Schlecht: Der Leser hat keine Ahnung, was das ist.
return '\ufeff' + content; // byte order mark	Gut: verwenden Sie Escapes für nicht druckbare Zeichen und kommentieren Sie ggf.

Tipp: Machen Sie Ihren Code niemals weniger lesbar, nur aus Angst, dass einige Programme Nicht-ASCII-Zeichen nicht richtig verarbeiten können. Wenn das passieren sollte, sind diese Programme kaputt und müssen repariert werden.

3 Struktur der Quelldatei

Genau eine Leerzeile trennt jeden Abschnitt, der vorhanden ist.

3.1 Lizenz- oder Copyright-Informationen, falls vorhanden

Wenn Lizenz- oder Copyright-Informationen in eine Datei gehören, gehören sie hierher.

3.2 Package-Anweisung

Die package-Anweisung ist nicht zeilenumbrochen. Das Spaltenlimit (Abschnitt 4.4, Spaltenlimit: 100) gilt nicht für package-Anweisungen.

3.3 Import-Anweisungen

3.3.1 Keine Platzhaltimporte

Platzhaltimporte, statisch oder anderweitig, werden nicht verwendet.

3.3.2 Kein Zeilenumbruch

Importanweisungen werden nicht zeilenumbrochen. Das Spaltenlimit (Abschnitt 4.4, Spaltenlimit: 100) gilt nicht für importstatements.

3.3.3 Reihenfolge und Abstand

Importe werden wie folgt geordnet:

1. Alle statischen Importe in einem einzigen Block.
2. Alle nicht statischen Importe in einem einzigen Block.

Wenn es sowohl statische als auch nicht statische Importe gibt, trennt eine einzelne Leerzeile die beiden Blöcke. Es gibt keine weiteren Leerzeilen zwischen Importanweisungen.

Innerhalb jedes Blocks werden die importierten Namen in ASCII-Sortierung angezeigt. (Hinweis: Dies ist nicht dasselbe wie die Importanweisungen in ASCII-Sortierreihenfolge seit ‚.’sortiert vor ‚;‘.)

3.3.4 Kein statischer Import für Klassen

Statischer Import wird nicht für statische verschachtelte Klassen verwendet. Sie werden mit importiertnormale Importe.

3.4 Klassendeklaration

3.4.1 Genau eine Klassendeklaration der obersten Ebene

Jede Klasse der obersten Ebene befindet sich in einer eigenen Quelldatei.

3.4.2 Reihenfolge der Klasseninhalte

Die Reihenfolge, die Sie für die Mitglieder und Initialisierer Ihrer Klasse auswählen, kann einen großen Einfluss auf die Lernfähigkeit haben. Es gibt jedoch kein einziges korrektes Rezept dafür; Verschiedene Klassen ordnen ihren Inhalt möglicherweise auf unterschiedliche Weise an.

Wichtig ist, dass jede Klasse eine logische Reihenfolge verwendet, die ihr Betreuer auf Anfrage erklären könnte. Zum Beispiel werden neue Methoden nicht nur gewohnheitsmäßig zum Ende der Klasse hinzugefügt, da dies zu einer Reihenfolge „chronologisch nach Datum hinzugefügt“ führen würde, was keine logische Reihenfolge ist.

3.4.2.1 Überlastungen: never split

Wenn eine Klasse mehrere Konstruktoren oder mehrere Methoden mit demselben Namen hat, erscheinen diese nacheinander, ohne anderen Code dazwischen (nicht einmal private Mitglieder).

4 Formatierung

Terminologie Hinweis: Blockähnliches Konstrukt bezieht sich aufder Körper einer Klasse, Methode oder Konstruktor. Beachten Sie, dass in Abschnitt 4.8.3.1 onarray initializers jeder Array Initializer optional so behandelt werden kann, als wäre es ein blockartiges Konstrukt.

4.1 Klammern

4.1.1 Klammern werden verwendet, wobei optionale

Klammern mitifelsefordo undwhile Anweisungen verwendet werden , auch wenn thebody leer ist oder nur eine einzige Anweisung enthält.

4.1.2 Nicht leere Blöcke: K & R-Stil

Klammern folgen dem Kernighan- und Ritchie-Stil(„Ägyptische Klammern“)für nicht leere Blöcke und blockähnliche Konstrukte:

• Kein Zeilenumbruch vor der öffnenden Klammer.
• Zeilenumbruch nach der öffnenden Klammer.
• Zeilenumbruch vor der schließenden Klammer.
• Zeilenumbruch nach der schließenden Klammer, nur wenn diese Klammer eine Anweisung oder den Hauptteil einer Methode, eines Konstruktors oder einer benannten Klasse beendet. Zum Beispiel gibt es keinen Zeilenumbruch nach der Klammer, wenn darauf else oder ein Komma folgt.

Beispiele:

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

Einige Ausnahmen für Enum-Klassen sind in Abschnitt 4.8.1,Enum-Klassen angegeben.

4.1.3 Leere Blöcke: kann prägnant sein

Ein leerer Block oder ein blockähnliches Konstrukt kann im K & R-Stil vorliegen (wie in Abschnitt 4.1.2 beschrieben). Alternativ kann es sofort nach dem Öffnen geschlossen werden, ohne Zeichen oder Zeilenumbrüche dazwischen ({}), es sei denn, es ist Teil einer amulti-block-Anweisung (eine, die direkt mehrere Blöcke enthält:if/else odertry/catch/finally).

Beispiele:

 // 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 Blockeinrückung: +2 Leerzeichen

Jedes Mal, wenn ein neuer Block oder ein blockähnliches Konstrukt geöffnet wird, erhöht sich der Einzug um zwei Leerzeichen. Wenn der Block endet, kehrt der Einzug zur vorherigen Einrückungsebene zurück. Die Einrückungsebene gilt sowohl für Code als auch für Kommentare im gesamten Block. (Siehe das Beispiel in Abschnitt 4.1.2,Nicht leere Blöcke: K & R Style.)

4.3 Eine Anweisung pro Zeile

Jeder Anweisung folgt ein Zeilenumbruch.

4.4 Spaltenlimit: 100

Java-Code hat ein Spaltenlimit von 100 Zeichen. Ein „Zeichen“ bedeutet einen beliebigen Unicode-Codepunkt.Außer wie unten erwähnt, muss jede Zeile, die diese Grenze überschreiten würde, Zeilenumbruch sein, wie in Abschnitt 4.5, Zeilenumbruch erläutert.

Jeder Unicode-Codepunkt zählt als ein Zeichen, auch wenn seine Anzeigebreite größer oder kleiner ist. Wenn Sie beispielsweise usingfullwidth-Zeichen verwenden, können Sie die Zeile früher umbrechen, als dies in dieser Regel unbedingt erforderlich ist.

Ausnahmen:

1. Zeilen, in denen die Einhaltung des Spaltenlimits nicht möglich ist (z. B. eine lange URL in Javadoc oder eine lange JSNI-Methodenreferenz).
2. package und import Anweisungen (siehe Abschnitte 3.2 Package-Anweisung und 3.3 Import-Anweisung).
3. Befehlszeilen in einem Kommentar, der in eine Shell eingefügt werden kann.

4.5 Zeilenumbruch

Terminologie Hinweis: Wenn Code, der sonst eine einzelne Zeile belegen könnte, in mehrere Zeilen aufgeteilt wird, wird diese Aktivität aufgerufen Zeilenumbruch.

Es gibt keine umfassende, deterministische Formel, die genau zeigt, wie in jeder Situation Zeilenumbrüche vorgenommen werden. Sehr oft gibt es mehrere gültige Möglichkeiten, denselben Code in eine Zeile zu schreiben.Hinweis: Während der typische Grund für den Zeilenumbruch darin besteht, das Überschreiten des Spaltenlimits zu vermeiden, kann selbst Code, der tatsächlich in das Spaltenlimit passt, nach Ermessen des Autors zeilenumbrochen werden.

Tipp: Das Extrahieren einer Methode oder lokalen Variablen kann das Problem lösenohne Zeilenumbruch.

4.5.1 Where to break

Die erste Direktive des Zeilenumbruchs lautet: lieber auf einer höheren syntaktischen Ebene brechen. Außerdem:

1. Wenn eine Zeile an einem Nicht Zuweisungsoperator unterbrochen wird, kommt der Bruch vor dem Symbol. (Beachten Sie, dass dies nicht die gleiche Praxis ist, die im Google-Stil für andere Sprachen wie C ++ und JavaScript verwendet wird.)
   • Dies gilt auch für die folgenden „operatorähnlichen“ Symbole:
     • das Punkttrennzeichen (.)
     • die beiden Doppelpunkte einer Methodenreferenz (::)
     • ein kaufmännisches und in einem Typ gebunden (<T extends Foo & Bar>)
     • eine Pipe in einem Catch-Block (catch (FooException | BarException e)).
2. Wenn eine Zeile an einem Zuweisungsoperator unterbrochen wird, kommt der Bruch normalerweise nach dem Symbol, aber so oder so ist akzeptabel.
   • Dies gilt auch für den Doppelpunkt „assignment-operator-like“ in einer erweiterten for („foreach“) Anweisung.
3. Ein Methoden- oder Konstruktorname bleibt an die offene Klammer angehängt ((), die darauf folgt.
4. Ein Komma (,) bleibt an das Token angehängt, das ihm vorausgeht.
5. Eine Zeile wird in einem Lambda niemals neben dem Pfeil unterbrochen, außer dass ein Bruch unmittelbar nach dem Pfeil erfolgen kann, wenn der Körper des Lambda aus einem einzelnen unverzweigten Ausdruck besteht. Beispiele:

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

Hinweis: Das primäre Ziel für Zeilenumbrüche ist es, Clearcode zu haben, nicht unbedingt Code, der in die kleinste Anzahl von Zeilen passt.

4.5.2 Fortsetzungszeilen mindestens +4 Leerzeichen einrücken

Beim Zeilenumbruch wird jede Zeile nach der ersten (jede Fortsetzungszeile) mindestens +4 von der ursprünglichen Zeile eingerückt.

Wenn mehrere Fortsetzungslinien vorhanden sind, kann die Einrückung über +4 hinaus variiert werden. Im Allgemeinen verwenden zwei Fortsetzungszeilen genau dann dieselbe Einrückungsebene, wennbeginnen Sie mit syntaktisch parallelen Elementen.

Abschnitt 4.6.3 zur horizontalen Ausrichtung befasst sich mit der entmutigten Praxis, eine variable Anzahl von Leerzeichen zu verwenden, um bestimmte Token mit vorherigen Zeilen auszurichten.

4.6 Whitespace

4.6.1 Vertikaler Whitespace

Es erscheint immer eine einzelne Leerzeile:

1. Zwischen aufeinanderfolgenden Mitgliedern oder Initialisierern einer Klasse: felder, Konstruktoren, Methoden, verschachtelte Klassen, statische Initialisierer und Instanzinitialisierer.
   • Ausnahme: Eine Leerzeile zwischen zwei aufeinanderfolgenden Feldern (mit keinem anderen Code dazwischen) ist optional. Solche Leerzeilen werden nach Bedarf verwendet, um logische Gruppierungen von Feldern zu erstellen.
   • Ausnahme: Leerzeilen zwischen Enum-Konstanten werden in Abschnitt 4.8.1 behandelt.
2. Wie in anderen Abschnitten dieses Dokuments gefordert (z. B. Abschnitt 3, Quelldateistruktur und Abschnitt 3.3, Importanweisungen).

Eine einzelne Leerzeile kann auch überall dort erscheinen, wo sie die Lesbarkeit verbessert, z. B. betweenstatements , um den Code in logische Unterabschnitte zu organisieren. Eine Leerzeile vor dem ersten Mitglied oder Initialisierer oder nach dem letzten Mitglied oder Initialisierer der Klasse wird weder ermutigt noch ermutigt.

Mehrere aufeinanderfolgende Leerzeilen sind erlaubt, aber niemals erforderlich (oder empfohlen).

4.6.2 Horizontal whitespace

Darüber hinaus, wo durch die Sprache oder andere Stilregeln erforderlich, und abgesehen von Literalen, Kommentare andJavadoc, ein einzelnes ASCII-Leerzeichen erscheint auch nur an den folgenden Stellen.

1. Trennen eines reservierten Wortes, wie iffor oder catch, von einer offenen Klammer ((), die auf diese Zeile folgt
2. Trennen eines reserviertes Wort, wie else oder catch, aus einer schließenden geschweiften Klammer (}), die ihm in dieser Zeile vorangestellt ist
3. Vor jeder offenen geschweiften Klammer ({), mit zwei Ausnahmen:
   • @SomeAnnotation({a, b}) (es wird kein Leerzeichen verwendet)
   • String x = {{"foo"}}; (zwischen {{ ist kein Leerzeichen erforderlich, siehe Punkt 8 unten)
4. Auf beiden Seiten eines binären oder ternären Operators. Dies gilt auch für die folgenden „operatorähnlichen“ Symbole:
   • das kaufmännische Und in einer konjunktiven Typbindung: <T extends Foo & Bar>
   • die Pipe für einen Catch-Block, der mehrere Ausnahmen behandelt: catch (FooException | BarException e)
   • der Doppelpunkt (:) in einer erweiterten for („foreach“) Anweisung
   • der Pfeil in einem Lambda-Ausdruck: (String str) -> str.length()

   aber nicht

   • die beiden Doppelpunkte (::) einer Methodenreferenz, die wie Object::toString
   • geschrieben ist das Punkttrennzeichen (.), das wie object.toString()
5. Nach ,:; oder der schließenden Klammer ()) einer Besetzung
6. Auf beiden Seiten des doppelten Schrägstrichs (//), die beginnt einen Zeilenende-Kommentar. Hier sind mehrere Leerzeichen erlaubt, aber nicht erforderlich.
7. Zwischen dem Typ und der Variablen einer Deklaration: List<String> list
8. Optional nur innerhalb beider Klammern eines Array-Initialisierers
   • new int {5, 6} und new int { 5, 6 } sind beide gültig
9. Zwischen einer Typanmerkung und oder ....

Diese Regel wird niemals so interpretiert, dass sie zusätzlichen Platz am Anfang oder Ende einer Zeile erfordert oder verbietet.

4.6.3 Horizontale Ausrichtung: nie erforderlich

Terminologie Hinweis: Horizontale Ausrichtung ist das Hinzufügen einer variablen Anzahl zusätzlicher Leerzeichen in Ihrem Code mit dem Ziel, bestimmte Token direkt unter bestimmten anderen Token in vorherigen Zeilen anzuzeigen.

Diese Praxis ist erlaubt, wird aber von Google Style nie verlangt. Es ist nicht einmal erforderlich, die horizontale Ausrichtung an Stellen beizubehalten, an denen sie bereits verwendet wurde.

Hier ist ein Beispiel ohne Alignment, dann mit alignment:

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

Tipp: Alignment kann die Lesbarkeit verbessern, verursacht aber Probleme fürzukünftige Wartung. Betrachten Sie eine zukünftige Änderung, die nur eine Zeile berühren muss. Diese Änderung mayleave die früher ansprechende Formatierung verstümmelt, und das ist erlaubt. Häufigeres fordert den Codierer (vielleicht Sie) auf, Leerzeichen auch in benachbarten Zeilen anzupassen und möglicherweise eine kaskadierende Reihe von Neuformatierungen auszulösen. Diese einzeilige Änderung hat jetzt einen „Explosionsradius.“Dies kann im schlimmsten Fall zu sinnloser Arbeit führen, aber im besten Fall verdirbt es immer noch versionshistorische Informationen, verlangsamt Prüfer und verschärft Merge-Konflikte.

4.7 Klammern gruppieren: empfohlen

Optionale Gruppierungsklammern werden nur dann weggelassen, wenn Autor und Rezensent sich einig sind, dass es keine vernünftige Chance gibt, dass der Code ohne sie falsch interpretiert wird, noch hätten sie den Code einfacher lesbar gemacht. Es ist nicht vernünftig anzunehmen, dass für jeden Reader die gesamte Javaoperator-Prioritätstabelle gespeichert ist.

4.8 Spezifische Konstrukte

4.8.1 Enum-Klassen

Nach jedem Komma, das auf eine Enum-Konstante folgt, ist ein Zeilenumbruch optional. Zusätzliche Leerzeilen (normalerweise nur eine) sind ebenfalls zulässig. Dies ist eine Möglichkeit:

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

Eine Enum-Klasse ohne Methoden und ohne Dokumentation ihrer Konstanten kann optional wie ein Array-Initialisierer formatiert werden (siehe Abschnitt 4.8.3.1 onarray initializers ).

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

Da Enum-Klassen Klassen sind, gelten alle anderen Regeln für die Formatierung von Klassen.

4.8.2 Variablendeklarationen

4.8.2.1 Eine Variable pro Deklaration

Jede Variablendeklaration (Feld oder lokal) deklariert nur eine Variable: Deklarationen wieint a, b; werden nicht verwendet.

Ausnahme: Mehrere Variablendeklarationen sind im Header einerfor Schleife zulässig.

4.8.2.2 Bei Bedarf deklariert

Lokale Variablen werden normalerweise nicht zu Beginn ihres containingblock oder blockartigen Konstrukts deklariert. Stattdessen werden lokale Variablen in der Nähe des Punktes deklariert, an dem sie zuerst verwendet werden (im Rahmen des Zumutbaren), um ihren Umfang zu minimieren. Lokale Variablendeklarationen haben Typischinitialisierer oder werden unmittelbar nach der Deklaration initialisiert.

4.8.3 Arrays

4.8.3.1 Array-Initialisierer: kann „blockartig“ sein

Jeder Array-Initialisierer kann optional so formatiert werden, als wäre er ein „block-likeconstruct .“ Zum Beispiel sind alle folgenden gültig (keine erschöpfende Liste):

new int { new int { 0, 1, 2, 3 0,} 1, 2,new int { 3, 0, 1, } 2, 3} new int {0, 1, 2, 3}

4.8.3.2 Keine Array-Deklarationen im C-Stil

Die eckigen Klammern bilden einen Teil des Typs, nicht die Variable:String args, nichtString args.

4.8.4 Switch-Anweisungen

Terminologie Hinweis: Innerhalb der geschweiften Klammern des aswitch-Blocks befinden sich eine oder mehrere Anweisungsgruppen. Jede Anweisungsgruppe besteht aus einer oder mehreren Schalterbeschriftungen (entweder case FOO: oderdefault:), gefolgt von einer oder mehreren Anweisungen (oder, für die letzte Anweisungsgruppe, null oder mehr Anweisungen).

4.8.4.1 Einrückung

Wie bei jedem anderen Block wird der Inhalt eines Schalterblocks +2 eingerückt.

Nach einer Schalterbeschriftung gibt es einen Zeilenumbruch, und die Einrückung wird +2 erhöht, genauwie wenn ein Block geöffnet würde. Die folgende Schalterbeschriftung kehrt zur vorherigen Einrückungsebene zurück, als wäre ein Block geschlossen worden.

4.8.4.2 Durchfallen: kommentiert

Innerhalb eines Switch-Blocks wird jede Anweisungsgruppe entweder abrupt beendet (mit einerbreakcontinuereturn oder einer ausgelösten Ausnahme) oder mit einem Kommentar markiert, um anzuzeigen, dass die Ausführung in der nächsten Anweisungsgruppe fortgesetzt wird oder fortgesetzt werden könnte. Jeder Kommentar, der die Idee des Fall-Through kommuniziert, ist ausreichend (typischerweise// fall through ). Dieser spezielle Kommentar ist nicht erforderlichdie letzte Anweisungsgruppe des Switch-Blocks. Beispiel:

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

Beachten Sie, dass nach case 1:nur am Ende der Anweisungsgruppe kein Kommentar erforderlich ist.

4.8.4.3 Der default Fall ist vorhanden

Jede switch-Anweisung enthält eine default statementgroup, auch wenn sie keinen Code enthält.

Ausnahme: Eine switch-Anweisung für einen enum -Typ kann die default -Anweisungsgruppe weglassen, wenn sie explizite Fälle enthält, die alle möglichen Werte dieses Typs abdecken. Dadurch können IDEs oder andere Staticanalysis-Tools eine Warnung ausgeben, wenn Fälle übersehen wurden.

4.8.5 Anmerkungen

Anmerkungen, die sich auf eine Klasse, Methode oder einen Konstruktor beziehen, werden unmittelbar nach dem Dokumentblock angezeigt, und jede Anmerkung wird in einer eigenen Zeile aufgeführt (dh eine Anmerkung pro Zeile). Diese Zeilenumbrüche stellen keinen Zeilenumbruch dar (Abschnitt 4.5, Zeilenumbruch), daher wird der Einrückungsgrad nicht erhöht. Beispiel:

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

Ausnahme: Eine einzelne parameterlose Annotation kann stattdessen zusammen mit der ersten Zeile der Signatur erscheinen, zum Beispiel:

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

Annotationen, die auf ein Feld angewendet werden, erscheinen auch unmittelbar nach dem Dokumentationsblock, aber in diesem Fall können mehrere Annotationen (möglicherweise parametrisiert) in derselben Zeile aufgeführt sein;zum Beispiel:

@Partial @Mock DataLoader loader;

Es gibt keine spezifischen Regeln für die Formatierung von Annotationen auf Parameter, lokale Variablen oder Typen.

Dieser Abschnitt behandelt Implementierungskommentare. Javadoc wird separat in Abschnitt 7, Javadoc behandelt.

Jedem Zeilenumbruch kann ein beliebiges Leerzeichen gefolgt von einem Implementierungskommentar vorangestellt werden.Ein solcher Kommentar macht die Zeile nicht leer.

4.8.6.1 Blockkommentarstil

Blockkommentare werden auf der gleichen Ebene wie der umgebende Code eingerückt. Sie können im Stil/* ... */ oder// ... sein. Bei mehrzeiligen/* ... */ -Kommentaren müssen nachfolgende Zeilen mit* beginnen, die mit der * in der vorherigen Zeile übereinstimmen.

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

Kommentare werden nicht in Kästchen mit Sternchen oder anderen Zeichen eingeschlossen.

Tipp: Verwenden Sie beim Schreiben von mehrzeiligen Kommentaren den/* ... */ -Stil, wenn Sie möchten, dass automatische Codeformatierer die Zeilen bei Bedarf umbrechen (Absatzstil). Die meisten Formatierer wickeln Zeilen nicht in// ... Stilkommentarblöcke ein.

4.8.7 Modifikatoren

Klassen- und Member-Modifikatoren werden, sofern vorhanden, in der von der Java-Sprachspezifikation empfohlenen Reihenfolge angezeigt:

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

4.8.8 Numerische Literale

long-ganzzahlige Literale verwenden einen Großbuchstaben L Suffix, nie Kleinbuchstaben (um Verwechslungen mit der Ziffer zu vermeiden 1). Zum Beispiel 3000000000Lstatt 3000000000l.

5 Benennung

5.1 Regeln, die allen Bezeichnern gemeinsam sind

Bezeichner verwenden nur ASCII-Buchstaben und -Ziffern und in einigen wenigen unten aufgeführten Fällen Unterstriche. Daher wird jeder gültige Bezeichner durch den regulären Ausdruck\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.

Klassennamen sind in der Regel Substantive oder Nominalphrasen. Beispiel:Character oderImmutableList. Schnittstellennamen können auch Substantive oder Substantivphrasen sein (z. B. List), manchmal aber auch Adjektive oder Adjektivphrasen (z. B.Readable).

Es gibt keine spezifischen Regeln oder sogar etablierte Konventionen für die Benennung von Annotationstypen.

Testklassen werden benannt, beginnend mit dem Namen der Klasse, die sie testen, und endendmit Test. Beispiel:HashTest oderHashIntegrationTest.

5.2.3 Methodennamen

Methodennamen werden in Kleinbuchstaben geschrieben.

Methodennamen sind typischerweise Verben oder Verbphrasen. Beispiel:sendMessage oderstop.

Unterstriche können in JUnit-Testmethodennamen erscheinen, um logische Komponenten von thename zu trennen, wobei jede Komponente in lowerCamelCase geschrieben wird.Ein typisches Muster ist <methodUnderTest>_<state>,zum Beispiel pop_emptyStack. Es gibt niemanden RichtigWeg, Testmethoden zu nennen.

5.2.4 Konstantennamen

Konstantennamen verwenden CONSTANT_CASE: alle Großbuchstaben, wobei jedes Wort durch einen einzelnen Unterstrich vom nächsten getrennt ist. Aber was ist aconstant genau?

Konstanten sind statische Endfelder, deren Inhalt tief unveränderlich ist und deren Methoden keine erkennbaren Nebenwirkungen haben. Dies umfasst Grundelemente, Zeichenfolgen, unveränderliche Typen und Immutablecollections von unveränderlichen Typen. Wenn sich der beobachtbare Status der Instanz ändern kann, ist er nicht konstant. Die bloße Absicht, das Objekt niemals zu mutieren, reicht nicht aus. Beispiel:

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

Diese Namen sind typischerweise Substantive oder Nominalphrasen.

5.2.5 Nicht konstante Feldnamen

Nicht konstante Feldnamen (statisch oder anders) werden in Kleinbuchstaben geschrieben.

Diese Namen sind in der Regel Substantive oder Substantivphrasen. Zum BeispielcomputedValues oderindex.

5.2.6 Parameternamen

Parameternamen werden in Kleinbuchstaben geschrieben.

Ein-Zeichen-Parameternamen in öffentlichen Methoden sollten vermieden werden.

5.2.7 Lokale Variablennamen

Lokale Variablennamen werden in Kleinbuchstaben geschrieben.

Selbst wenn sie endgültig und unveränderlich sind, werden lokale Variablen nicht als Konstanten betrachtet und sollten nicht als Konstanten formatiert werden.

5.2.8 Typvariablennamen

Jede Typvariable wird in einem von zwei Stilen benannt:

• Ein einzelner Großbuchstabe, optional gefolgt von einer einzelnen Ziffer (z. B. ETXT2)
• Ein Name in der für Klassen verwendeten Form (siehe Abschnitt 5.2.2, Klassennamen), gefolgt vom Großbuchstaben T (Beispiele: RequestTFooBarT).

5.3 Camel case: definiert

Manchmal gibt es mehr als eine vernünftige Möglichkeit, eine englische Phrase in Camel case umzuwandeln, z. B. wenn Akronyme oder ungewöhnliche Konstrukte wie „IPv6“ oder „iOS“ vorhanden sind. Um die Vorhersagbarkeit zu verbessern, gibt Google Style das folgende (fast) deterministische Schema an.

Beginnend mit der Prosaform des Namens:

1. Konvertieren Sie die Phrase in einfaches ASCII und entfernen Sie alle Apostrophe. Zum Beispiel könnte „Müllers Algorithmus“ zu „Müllers Algorithmus“ werden.
2. Teilen Sie dieses Ergebnis in Wörter auf, wobei Sie Leerzeichen und alle verbleibenden Satzzeichen (normalerweise Bindestriche) aufteilen.
   • Empfohlen: Wenn ein Wort im allgemeinen Sprachgebrauch bereits ein herkömmliches Camel-Case-Erscheinungsbild aufweist, teilen Sie es in seine Bestandteile auf (z. B. „AdWords“ wird zu „Anzeigenwörtern“). Beachten Sie, dass ein Wort wie „iOS“ nicht wirklich in Camel case per se ist; Es widerspricht jeder Konvention, daher gilt diese Empfehlung nicht.
3. Jetzt Kleinbuchstaben alles (einschließlich Akronyme), dann Großbuchstaben nur das erste Zeichen von:
   • … jedes Wort, um Großbuchstaben zu erhalten, oder
   • … jedes Wort außer dem ersten, um Kleinbuchstaben zu erhalten
4. Schließlich verbinden Sie alle Wörter zu einem einzigen Bezeichner.

Beachten Sie, dass das Gehäuse der ursprünglichen Wörter fast vollständig ignoriert wird. Beispiel:

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: immer verwendet

Eine Methode wird mit der Annotation @Override markiert, wenn sie legal ist. Dies umfasst eine Klassenmethode, die eine Superklassenmethode überschreibt, eine Klassenmethodimplementierung einer Schnittstellenmethode und eine Schnittstellenmethode, die eine superinterfacemethod .

Ausnahme:@Override kann weggelassen werden, wenn die übergeordnete Methode@Deprecated ist.

6.2 Abgefangene Ausnahmen: nicht ignoriert

Außer wie unten erwähnt, ist es sehr selten richtig, als Reaktion auf eine caughtexception nichts zu tun. (Typische Antworten sind, es zu protokollieren, oder wenn es als „unmöglich“ angesehen wird, werfen Sie es erneut alsAssertionError .)

Wenn es wirklich angebracht ist, in einem Catch-Block keinerlei Maßnahmen zu ergreifen, wird der Grund dafür in einem Kommentar erläutert.

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

Ausnahme: In Tests kann eine abgefangene Ausnahme kommentarlos ignoriert werden, wenn ihr Name mit expected . Thefollowing ist ein sehr gebräuchliches Idiom, um sicherzustellen, dass der zu testende Code anexception des erwarteten Typs auslöst, sodass hier kein Kommentar erforderlich ist.

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

6.3 Statische Member: qualifiziert mit Klasse

Wenn ein Verweis auf ein statisches Klassenmitglied qualifiziert werden muss, wird es mit dem Namen dieser Klasse qualifiziert, nicht mit einem Verweis oder Ausdruck des Typs dieser Klasse.

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

6.4 Finalizer: nicht verwendet

Es ist äußerst selten, Object.finalize zu überschreiben.

Tipp: Tun Sie es nicht. Wenn Sie unbedingt müssen, lesen und verstehen Sie zuerst Artikel 7 von Effective Java, „Finalizer vermeiden“, sehr sorgfältig und tun Sie es dann nicht.

7 Javadoc

7.1 Formatierung

7.1.1 Allgemeine Form

Die grundlegende Formatierung von Javadoc-Blöcken ist wie in diesem Beispiel zu sehen:

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

… oder in diesem einzeiligen Beispiel:

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

Die Grundform ist immer akzeptabel. Die einzeilige Form kann ersetzt werden, wenn die Gesamtheit des Javadoc-Blocks (einschließlich Kommentarmarkierungen) in eine einzelne Zeile passen kann. Beachten Sie, dass dies nur gilt, wenn keine Block-Tags wie @return vorhanden sind.

7.1.2 Absätze

Zwischen Absätzen und vor der Gruppe der Block—Tags ifpresent wird eine Leerzeile angezeigt, dh eine Zeile, die nur das ausgerichtete führende Sternchen(*) enthält. Jeder Absatz außer dem ersten hat <p> unmittelbar vor dem ersten Wort, ohne Leerzeichen danach.

7.1.3 Block-Tags

Alle standardmäßigen „Block-Tags“, die verwendet werden, erscheinen in der Reihenfolge @param@return@throws@deprecated, und diese typen neverappear mit einer leeren Beschreibung. Wenn ein Block-Tag nicht in eine einzelne Zeile passt, werden Fortsetzungszeilensind vier (oder mehr) Leerzeichen von der Position des @ eingerückt.

7.2 Das Zusammenfassungsfragment

Jeder Javadoc-Block beginnt mit einem kurzen Zusammenfassungsfragment. Diesfragment ist sehr wichtig: Es ist der einzige Teil des Textes, der in bestimmten Kontexten wie Klassen- und Methodenindizes angezeigt wird.

Dies ist ein Fragment – eine Substantiv- oder Verbphrase, kein vollständiger Satz. Es beginnt nicht mit A {@code Foo} is a... oderThis method returns..., noch bildet es einen vollständigen Imperativsatz wie Save the record. . Das Fragment wird jedoch groß geschrieben undpunktiert, als wäre es ein vollständiger Satz.

Tipp: Ein häufiger Fehler besteht darin, einfaches Javadoc in der Form/** @return the customer ID */ zu schreiben. Dies ist falsch und sollte in /** Returns the customer ID. */ geändert werden.

7.3 Wo Javadoc verwendet wird

Mindestens ist Javadoc für jedepublic Klasse und jedespublic oderprotected Mitglied einer solchen Klasse vorhanden, mit einigen Ausnahmen, die unten aufgeführt sind.

Es kann auch zusätzlicher Javadoc-Inhalt vorhanden sein, wie in Abschnitt 7.3.4, Nicht erforderliches Javadoc erläutert.

7.3.1 Ausnahme: selbsterklärende Methoden

Javadoc ist optional für „einfache, offensichtliche“ Methoden wiegetFoo, in Fällen, in denen es wirklich und wahrhaftig nichts anderes gibt, als „Das foo zurückzugeben“.

Wichtig: es ist nicht angebracht, diese Ausnahme zu zitieren, um relevante Informationen zu rechtfertigen, die ein typischer Leser möglicherweise wissen muss. Lassen Sie beispielsweise für eine Methode mit dem Namen getCanonicalName deren Dokumentation nicht weg (mit der Begründung, dass nur/** Returns the canonical name. */ ), wenn ein typischer Leser möglicherweise keine Ahnung hat, was der Begriff „kanonischer Name“ bedeutet!

7.3.2 Ausnahme: Überschreibungen

Javadoc ist nicht immer bei einer Methode vorhanden, die eine Supertype-Methode überschreibt.

7.3.4 Nicht erforderliches Javadoc

Andere Klassen und Mitglieder haben Javadoc nach Bedarf oder Wunsch.