Kotlin-Styleguide

Dieses Dokument enthält die vollständige Definition der Android-Programmierstandards von Google für Quellcode in Kotlin. Eine Kotlin-Quelldatei wird nur dann als im Google Android-Stil enthalten beschrieben, wenn sie den hier aufgeführten Regeln entspricht.

Wie bei anderen Programmier-Styleguides wurden hier nicht nur ästhetische Probleme der Formatierung behandelt, sondern auch andere Arten von Konventionen oder Codierungsstandards. Dieses Dokument konzentriert sich jedoch hauptsächlich auf die festen und schnellen Regeln, die wir allgemein befolgen, und vermeidet Ratschläge, die nicht eindeutig durchsetzbar sind (ob durch Menschen oder Tools).

Letzte Aktualisierung: 06.09.2023

Quelldateien

Alle Quelldateien müssen UTF-8-codiert sein.

Benennung

Wenn eine Quelldatei nur eine einzige Klasse der obersten Ebene enthält, wird der Dateiname sollte dem Namen und der Erweiterung .kt unter Beachtung der Groß- und Kleinschreibung entsprechen. Andernfalls Wenn eine Quelldatei mehrere Deklarationen der obersten Ebene enthält, wählen Sie einen Namen aus. der den Inhalt der Datei beschreibt, wenden Sie PascalCase (CamelCase ist zulässig, wenn der Dateiname im Plural verwendet wird) und hängen Sie die Erweiterung .kt an.

// MyClass.kt
class MyClass { }

// Bar.kt
class Bar { }
fun Runnable.toBar(): Bar = // …

// Map.kt
fun <T, O> Set<T>.map(func: (T) -> O): List<O> = // …
fun <T, O> List<T>.map(func: (T) -> O): List<O> = // …

// extensions.kt
fun MyClass.process() = // …
fun MyResult.print() = // …

Sonderzeichen

Leerzeichen

Abgesehen von der Abfolge des Linienabschlusszeichens Horizontales ASCII-Leerzeichen (0 x 20) ist das einzige Leerzeichen, das irgendwo in einer Quelldatei angezeigt wird. Dies impliziert Folgendes:

• Alle anderen Leerzeichen in String- und Zeichenliteralen werden mit Escapezeichen versehen.
• Tabulatorzeichen werden nicht für den Einzug verwendet.

Spezielle Escapesequenzen

Für alle Zeichen, die eine spezielle Escapesequenz haben (\b, \n, \r, \t, \', \", \\ und \$), wird diese Sequenz statt des entsprechenden Unicode-Zeichens (z.B. \u000a)-Escapesequenz eingefügt werden.

Nicht-ASCII-Zeichen

Für die übrigen Nicht-ASCII-Zeichen wird entweder das tatsächliche Unicode-Zeichen (z.B. ∞) oder ein entsprechendes Unicode-Escapezeichen (z.B. \u221e) verwendet wird. Die Wahl hängt nur davon ab, wodurch der Code leichter zu lesen und zu verstehen. Unicode-Escape-Zeichen werden für druckbare Zeichen an allen Speicherorten und von Stringliteralen und Kommentaren wird dringend abgeraten.

Beispiel	Diskussion
val unitAbbrev = "μs"	Am besten: absolut klar, auch ohne Kommentar.
val unitAbbrev = "\u03bcs" // μs	Schlecht: Es gibt keinen Grund, ein Escapezeichen für ein druckbares Zeichen zu verwenden.
val unitAbbrev = "\u03bcs"	Schlecht: Der Leser weiß nicht, was das ist.
return "\ufeff" + content	Gut: Verwenden Sie Escape-Zeichen für nicht druckbare Zeichen und kommentieren Sie, falls erforderlich.

Struktur

Eine .kt-Datei enthält Folgendes in der richtigen Reihenfolge:

• Überschrift für Urheberrecht und/oder Lizenz (optional)
• Anmerkungen auf Dateiebene
• Paketanweisung
• Importanweisungen
• Deklarationen der obersten Ebene

Jeder dieser Abschnitte ist durch genau eine Leerzeile voneinander getrennt.

Urheberrecht / Lizenz

Wenn ein Urheberrechts- oder Lizenzheader in die Datei gehört, sollte dieser in einem mehrzeiligen Kommentar ganz oben platziert werden.

/*
 * Copyright 2017 Google, Inc.
 *
 * ...
 */
 

Verwende keinen KDoc-Stil. oder einzeiligen Kommentar.

/**
 * Copyright 2017 Google, Inc.
 *
 * ...
 */

// Copyright 2017 Google, Inc.
//
// ...

Anmerkungen auf Dateiebene

Annotationen mit „file“ Website-Ziel verwenden zwischen einem Headerkommentar und der Paketdeklaration platziert werden.

Paketanweisung

Die Paketanweisung unterliegt keinem Spaltenlimit und wird niemals zeilenweise umgebrochen.

Importanweisungen

Importanweisungen für Klassen, Funktionen und Eigenschaften werden in einer einzigen Liste gruppiert und nach ASCII sortiert.

Platzhalterimporte sind jeglicher Art nicht zulässig.

Ähnlich wie bei der Paketanweisung unterliegen Importanweisungen keiner Spaltenlimit und niemals Zeilenumbruch.

Deklarationen der obersten Ebene

In einer .kt-Datei können ein oder mehrere Typen, Funktionen, Eigenschaften oder Typen deklariert werden. -Aliase auf oberster Ebene.

Der Inhalt einer Datei sollte sich auf ein einzelnes Thema konzentrieren. Beispiele dafür wäre ein einzelner öffentlicher Typ oder eine Reihe von Erweiterungsfunktionen, die die für mehrere Empfängertypen verwenden. Unzugehörige Deklarationen sollten in eigene Dateien und öffentliche Erklärungen in einer Datei aufgeteilt. sollte auf ein Minimum reduziert werden.

Es wird keine ausdrückliche Einschränkung hinsichtlich der Anzahl oder Reihenfolge der Inhalte aufgestellt. in einer Datei.

Quelldateien werden normalerweise von oben nach unten gelesen. Das bedeutet, im Allgemeinen, sollten berücksichtigen, dass die Erklärungen auf höherer Ebene weiter unten verstehen können. Unterschiedliche Dateien werden möglicherweise sortiert unterschiedlich sein. Entsprechend kann eine Datei 100 Eigenschaften enthalten, weitere 10 Funktionen und noch eine einzelne Klasse.

Wichtig ist, dass jede Datei eine logische Reihenfolge verwendet, könnte die Pflegekraft erklären, wenn sie dazu aufgefordert wird. Neue Funktionen sind beispielsweise nicht nur häufig am Ende der Datei hinzugefügt, da dies zu "chronologischen nach hinzugefügtem Datum“, was keine logische Sortierung ist.

Sortierung der Kursmitglieder

Für die Reihenfolge der Mitglieder in einem Kurs gelten dieselben Regeln wie für die oberste Ebene. Deklarationen.

Formatierung

Zahnspangen

Für when-Zweige und if-Ausdrücke sind keine Klammern erforderlich die nicht mehr als einen else-Zweig haben und auf eine einzelne Linie passen.

if (string.isEmpty()) return

val result =
    if (string.isEmpty()) DEFAULT_VALUE else string

when (value) {
    0 -> return
    // …
}

Andernfalls sind für jeden if-, for-, when-Zweig, do, und while-Anweisungen und -Ausdrücke, auch wenn der Text leer ist oder nur einer einzelnen Anweisung.

if (string.isEmpty())
    return  // WRONG!

if (string.isEmpty()) {
    return  // Okay
}

if (string.isEmpty()) return  // WRONG
else doLotsOfProcessingOn(string, otherParametersHere)

if (string.isEmpty()) {
    return  // Okay
} else {
    doLotsOfProcessingOn(string, otherParametersHere)
}

Nicht leere Blöcke

Klammern folgen dem Kernighan- und Ritchie-Stil ("ägyptische Klammern") für nicht leeren Blöcken und blockähnlichen Konstrukten:

• Kein Zeilenumbruch vor der öffnenden Klammer
• Zeilenumbruch nach der öffnenden Klammer
• Zeilenumbruch vor der schließenden Klammer
• Zeilenumbruch nach der schließenden Klammer, nur dann, wenn diese geschweifte Klammer am Ende eines Anweisung oder beendet den Hauptteil einer Funktion, eines Konstruktors oder einer benannten Klasse. Beispiel: Nach der öffnenden Klammer ist kein Zeilenumbruch vorhanden, wenn auf else oder ein Komma.

return Runnable {
    while (condition()) {
        foo()
    }
}

return object : MyClass() {
    override fun foo() {
        if (condition()) {
            try {
                something()
            } catch (e: ProblemException) {
                recover()
            }
        } else if (otherCondition()) {
            somethingElse()
        } else {
            lastThing()
        }
    }
}

Einige Ausnahmen für Enum-Klassen sind im Folgenden aufgeführt.

Leere Blöcke

Ein leerer Block oder ein blockartiges Konstrukt müssen im K&R-Stil vorliegen.

try {
    doSomething()
} catch (e: Exception) {} // WRONG!

try {
    doSomething()
} catch (e: Exception) {
} // Okay

Ausdrücke

Eine if/else-Bedingung, die als Ausdruck verwendet wird, kann Lassen Sie nur geschweifte Klammern weg, wenn der gesamte Ausdruck in eine Zeile passt.

val value = if (string.isEmpty()) 0 else 1  // Okay

val value = if (string.isEmpty())  // WRONG!
    0
else
    1

val value = if (string.isEmpty()) { // Okay
    0
} else {
    1
}

Einzug

Jedes Mal, wenn ein neuer Block oder ein blockähnliches Konstrukt geöffnet wird, wird der Einzug um vier Leerzeichen erhöht. Wenn der Block endet, wird die Einrückung wieder auf die vorherige Einrückungsebene zurückgesetzt. Die Einrückung gilt sowohl für Code als auch für Kommentare im gesamten Block.

Eine Anweisung pro Zeile

Auf jede Anweisung folgt ein Zeilenumbruch. Es werden keine Semikolons verwendet.

Zeilenumbruch

Der Code darf maximal 100 Zeichen lang sein. Außer wie unten angegeben muss jede Zeile, die diesen Grenzwert überschreiten würde, wie unten erläutert umgebrochen werden.

Ausnahmen:

• Zeilen, bei denen die Einhaltung des Spaltenlimits nicht möglich ist (z. B. eine lange URL in KDoc)
• Anweisungen package und import
• Befehlszeilen in einem Kommentar, die ausgeschnitten und in eine Shell eingefügt werden können

Pause

Die wichtigste Anweisung des Zeilenumbruchs lautet: Die Unterbrechung soll auf einer höheren Syntaxebene vorgezogen werden. Weitere Hinweise:

• Wenn eine Zeile bei einem Operator oder Infix-Funktionsnamen unterbrochen wird, erscheint der Umbruch nach dem Operator- oder Infix-Funktionsnamen ein.
• Wird eine Linie durch die folgenden Symbole wie „operatorähn“ unterbrochen, wird der Umbruch vor dem Symbol steht: <ph type="x-smartling-placeholder">
  </ph>
  • Das Punkttrennzeichen (., ?.).
  • Die beiden Doppelpunkte einer Mitgliederreferenz (::).
• Ein Methoden- oder Konstruktorname bleibt an die offene Klammer (() angehängt, die folgt.
• Ein Komma (,) bleibt an das vorangehende Token angehängt.
• Ein Lambda-Pfeil (->) bleibt an die vorherige Argumentliste angehängt.

Funktionen

Wenn eine Funktionssignatur nicht in eine einzelne Zeile passt, unterteilen Sie jede Parameterdeklaration in eine eigene Zeile. In diesem Format definierte Parameter sollten einen einzelnen Einzug (+4) verwenden. Die schließende Klammer ()) und der Rückgabetyp werden in einer eigenen Zeile ohne zusätzlichen Einzug platziert.

fun <T> Iterable<T>.joinToString(
    separator: CharSequence = ", ",
    prefix: CharSequence = "",
    postfix: CharSequence = ""
): String {
    // …
}

Ausdrucksfunktionen

Wenn eine Funktion nur einen einzelnen Ausdruck enthält, kann sie als ein Ausdrucksfunktion

override fun toString(): String {
    return "Hey"
}

override fun toString(): String = "Hey"

Properties

Wenn ein Eigenschafteninitialisierer nicht in eine einzelne Zeile passt, brechen Sie den Zeilenumbruch nach dem Gleichheitszeichen (=) ab und verwenden Sie einen Einzug.

private val defaultCharset: Charset? =
    EncodingRegistry.getInstance().getDefaultCharsetForPropertiesFiles(file)

Properties, die eine get- und/oder set-Funktion deklarieren, sollten jeweils in eine eigene Zeile mit normalem Einzug (+4) einfügen. Verwenden Sie dieselben Regeln, als Funktionen.

var directory: File? = null
    set(value) {
        // …
    }

Schreibgeschützte Properties können eine kürzere Syntax verwenden, die auf eine einzelne Zeile passt.

val defaultExtension: String get() = "kt"

Leerraum

Vertikal

Eine einzelne Leerzeile wird angezeigt:

• Zwischen aufeinanderfolgenden Mitgliedern einer Klasse: Properties, Konstruktoren, Funktionen, verschachtelte Klassen usw. <ph type="x-smartling-placeholder">
  </ph>
  • Ausnahme:Eine Leerzeile zwischen zwei Aufeinanderfolgende Properties (ohne anderen Code dazwischen) ist optional. Solche Leerzeilen werden nach Bedarf verwendet, um Logische Gruppierungen von Properties und verknüpfte Properties sofern vorhanden.
  • Ausnahme:Leerzeilen zwischen enum-Konstanten werden abgedeckt. unten.
• Zwischen Anweisungen, nach Bedarf, um den Code zu organisieren in logische Unterabschnitte unterteilen.
• Optional vor der ersten Anweisung in einer Funktion: oder nach dem letzten Mitglied eines Kurses (weder ermutigt noch entmutigt).
• Wenn dies in anderen Abschnitten dieses Dokuments vorgesehen ist (z. B. <ph type="x-smartling-placeholder"></ph> Struktur).

Mehrere aufeinanderfolgende Leerzeilen sind erlaubt, aber nicht empfohlen oder erforderlich sind.

Horizontal

Über die Anforderungen der Sprache oder anderen Stilregeln hinaus und abgesehen von Literalen, Kommentaren und KDoc, -Bereich auch nur an folgenden Stellen zu sehen ist:

• Trennen von reservierten Wörtern wie if, for oder catch durch eine offene Klammer ((), die in dieser Zeile darauf folgt.

  // WRONG!
  for(i in 0..1) {
  }
  

  // Okay
  for (i in 0..1) {
  }
  

• Reservierte Wörter voneinander trennen, z. B. else oder catch, von einem Schließende geschweifte Klammer (}), die in dieser Zeile davor steht.

  // WRONG!
  }else {
  }
  

  // Okay
  } else {
  }
  

• Vor jeder geöffneten geschweiften Klammer ({).

  // WRONG!
  if (list.isEmpty()){
  }
  

  // Okay
  if (list.isEmpty()) {
  }
  

• Auf beiden Seiten eines binären Operators

  // WRONG!
  val two = 1+1
  

  // Okay
  val two = 1 + 1
  

  Dies gilt auch für die folgenden "operatorähnlichen" Symbole: <ph type="x-smartling-placeholder">
  </ph>
  • Pfeil in einem Lambda-Ausdruck (->)

    // WRONG!
    ints.map { value->value.toString() }
    

    // Okay
    ints.map { value -> value.toString() }
    

  Aber nicht: <ph type="x-smartling-placeholder">
  </ph>
  • Die beiden Doppelpunkte (::) einer Mitgliederreferenz.

    // WRONG!
    val toString = Any :: toString
    

    // Okay
    val toString = Any::toString
    

  • das Punkttrennzeichen (.).

    // WRONG
    it . toString()
    

    // Okay
    it.toString()
    

  • Bereichsoperator (..)

    // WRONG
    for (i in 1 .. 4) {
      print(i)
    }
    

    // Okay
    for (i in 1..4) {
      print(i)
    }
    

• Nur vor einem Doppelpunkt (:), wenn er in einer Klassendeklaration zur Angabe von einer Basisklasse oder Schnittstellen oder wenn sie in einer where-Klausel verwendet werden für <ph type="x-smartling-placeholder"></ph> allgemeine Einschränkungen.

  // WRONG!
  class Foo: Runnable
  

  // Okay
  class Foo : Runnable
  

  // WRONG
  fun <T: Comparable> max(a: T, b: T)
  

  // Okay
  fun <T : Comparable> max(a: T, b: T)
  

  // WRONG
  fun <T> max(a: T, b: T) where T: Comparable<T>
  

  // Okay
  fun <T> max(a: T, b: T) where T : Comparable<T>
  

• Nach einem Komma (,) oder Doppelpunkt (:).

  // WRONG!
  val oneAndTwo = listOf(1,2)
  

  // Okay
  val oneAndTwo = listOf(1, 2)
  

  // WRONG!
  class Foo :Runnable
  

  // Okay
  class Foo : Runnable
  

• Auf beiden Seiten des doppelten Schrägstrichs (//), der mit einem am Zeilenende. Hier sind mehrere Leerzeichen erlaubt, aber nicht erforderlich.

  // WRONG!
  var debugging = false//disabled by default
  

  // Okay
  var debugging = false // disabled by default
  

Diese Regel wird niemals als erforderlich oder unzulässig ausgelegt zusätzlicher Abstand am Anfang oder Ende einer Zeile sie bezieht sich nur auf den Innenraum.

Spezifische Konstrukte

Enum-Klassen

Eine Aufzählung ohne Funktionen und ohne Dokumentation ihrer Konstanten kann optional als einzelne Zeile formatiert werden.

enum class Answer { YES, NO, MAYBE }

Wenn die Konstanten in einer Enum auf separaten Zeilen platziert werden, ist zwischen ihnen keine Leerzeile erforderlich, außer wenn sie einen Textkörper definieren.

enum class Answer {
    YES,
    NO,

    MAYBE {
        override fun toString() = """¯\_(ツ)_/¯"""
    }
}

Da es sich bei enum-Klassen um Klassen handelt, gelten alle anderen Regeln für Formatierungsklassen.

Anmerkungen

Mitglieder- oder Typanmerkungen werden in separaten Zeilen unmittelbar vor dem annotierten Konstrukt platziert.

@Retention(SOURCE)
@Target(FUNCTION, PROPERTY_SETTER, FIELD)
annotation class Global

Anmerkungen ohne Argumente können in einer einzelnen Zeile eingefügt werden.

@JvmField @Volatile
var disposable: Disposable? = null

Wenn nur eine Anmerkung ohne Argumente vorhanden ist, Er kann in derselben Zeile wie die -Deklaration platziert werden.

@Volatile var disposable: Disposable? = null

@Test fun selectAll() {
    // …
}

Die @[...]-Syntax darf nur mit einem expliziten User-Site-Ziel und nur für Kombiniert zwei oder mehr Anmerkungen ohne Argumente in einer einzigen Zeile.

@field:[JvmStatic Volatile]
var disposable: Disposable? = null

Implizite Rückgabe/Eigenschaftstypen

Wenn ein Ausdrucksfunktionstext oder ein Eigenschaftsinitialisierer ein skalarer Wert ist oder der Rückgabetyp eindeutig aus dem Text abgeleitet werden kann, können weggelassen werden.

override fun toString(): String = "Hey"
// becomes
override fun toString() = "Hey"

private val ICON: Icon = IconLoader.getIcon("/icons/kotlin.png")
// becomes
private val ICON = IconLoader.getIcon("/icons/kotlin.png")

Behalten Sie beim Schreiben einer Bibliothek die explizite Typdeklaration bei, wenn die Teil der öffentlichen API ist.

Benennung

Kennungen enthalten nur ASCII-Buchstaben und Ziffern sowie, in einigen wenigen Fällen, Unterstriche. Somit wird jeder gültige Kennungsname mit dem regulären Ausdruck \w+ abgeglichen.

Spezielle Präfixe oder Suffixe wie in den Beispielen gezeigt name_, mName, s_name und kName werden nur im folgenden Fall verwendet: Sicherungseigenschaften (siehe Sicherungseigenschaften).

Paketnamen

Paketnamen werden alle aus Kleinbuchstaben bestehen und einfach aufeinanderfolgende Wörter enthalten verkettet sind (keine Unterstriche).

// Okay
package com.example.deepspace
// WRONG!
package com.example.deepSpace
// WRONG!
package com.example.deep_space

Typnamen

Klassennamen werden in PascalCase geschrieben und sind typischerweise Substantive oder Substantive Wortgruppen. Beispiel: Character oder ImmutableList. Schnittstellennamen können auch Nomen oder Nominalphrasen sein (z. B. List), aber können manchmal Adjektive oder Adjektivsätze sein (z. B. Readable).

Testklassen beginnen mit dem Namen der Klasse, die sie testen. und endet auf Test. Beispiel: HashTest oder HashIntegrationTest.

Funktionsnamen

Funktionsnamen werden in CamelCase-Schreibweise geschrieben und sind typischerweise Verben oder Verbformulierungen. Beispiel: sendMessage oder stop.

In Testfunktionsnamen dürfen Unterstriche verwendet werden, um logische Komponenten des Namens voneinander zu trennen.

@Test fun pop_emptyStack() {
    // …
}

Mit @Composable annotierte Funktionen, die Unit zurückgeben, sind PascalCased und werden wie Substantive benannt, als wären sie Typen.

@Composable
fun NameTag(name: String) {
    // …
}

Funktionsnamen sollten keine Leerzeichen enthalten, da dies nicht in allen unterstützt wird -Plattform (insbesondere wird dies in Android nicht vollständig unterstützt).

// WRONG!
fun `test every possible case`() {}
// OK
fun testEveryPossibleCase() {}

Konstantennamen

In den Namen von Konstanten wird UPPER_SNAKE_CASE verwendet, also ausschließlich Großbuchstaben, mit Wörtern, die durch Unterstriche getrennt sind. Aber was ist eigentlich eine Konstante?

Konstanten sind val-Eigenschaften ohne benutzerdefinierte get-Funktion, deren Inhalt die stark unveränderlich sind und deren Funktionen keine erkennbaren Nebeneffekte haben. Dieses enthält unveränderliche Typen und unveränderliche Sammlungen unveränderlicher Typen sowie Skalare und Strings, wenn sie als const gekennzeichnet sind. Wenn der Status einer Instanz ob sich der beobachtbare Zustand ändern kann. Er ist keine Konstante. Die reine Absicht, mutate des Objekts reicht nicht aus.

const val NUMBER = 5
val NAMES = listOf("Alice", "Bob")
val AGES = mapOf("Alice" to 35, "Bob" to 32)
val COMMA_JOINER = Joiner.on(',') // Joiner is immutable
val EMPTY_ARRAY = arrayOf()

Diese Namen sind in der Regel Substantive oder Nominalphrasen.

Konstantenwerte können nur innerhalb eines object definiert werden oder als übergeordnete Deklaration. Werte, die anderweitig die Anforderung eines konstant, aber in class definiert, muss ein nicht konstanter Name verwendet werden.

Bei Konstanten, bei denen es sich um skalare Werte handelt, muss die const modifier ist.

Nicht konstante Namen

Nicht konstante Namen werden in CamelCase geschrieben. Diese gelten für Instanzattribute, lokale Attribute und Parameternamen.

val variable = "var"
val nonConstScalar = "non-const"
val mutableCollection: MutableSet = HashSet()
val mutableElements = listOf(mutableInstance)
val mutableValues = mapOf("Alice" to mutableInstance, "Bob" to mutableInstance2)
val logger = Logger.getLogger(MyClass::class.java.name)
val nonEmptyArray = arrayOf("these", "can", "change")

Diese Namen sind in der Regel Substantive oder Nominalphrasen.

Sicherungseigenschaften

Wenn ein Sicherungseigenschaft erforderlich ist, muss der Name genau mit dem der Immobilie übereinstimmen. außer dass ein Unterstrich vorangestellt ist.

private var _table: Map? = null

val table: Map
    get() {
        if (_table == null) {
            _table = HashMap()
        }
        return _table ?: throw AssertionError()
    }

Variablennamen eingeben

Jede Typvariable wird in einem von zwei Stilen benannt:

• Ein einfacher Buchstabe, optional gefolgt von einem einfache Ziffer (z. B. E, T, X, T2)
• Ein Name im Format des Kurses, gefolgt vom Großbuchstaben Buchstabe T (z. B. RequestT, FooBarT)

CamelCase

Manchmal gibt es mehr als eine sinnvolle Möglichkeit, eine englische Phrase in die Camel-Case-Schreibweise umzuwandeln, z. B. wenn Akronyme oder ungewöhnliche Konstrukte wie „IPv6“ oder „iOS“ vorhanden sind. Verwenden Sie das folgende Schema, um die Vorhersehbarkeit zu verbessern.

Beginnen Sie mit der Textform des Namens:

1. Konvertieren Sie die Wortgruppe in einfache ASCII-Zeichen und entfernen Sie alle Apostrophe. So könnte z. B. der Müller-Algorithmus zu „Muellers-Algorithmus“ werden.
2. Teile dieses Ergebnis in Wörter auf und teile es durch Leerzeichen und verbleibende Satzzeichen (in der Regel Bindestriche). Empfohlen:Wenn ein Wort bereits eine herkömmliche Camel-Case-Darstellung hat, teilen Sie es in die einzelnen Bestandteile auf (z.B. Aus "AdWords" wird nun "Anzeigenwörter". Beachten Sie, dass ein Wort wie "iOS" an sich nicht in der Camel-Case-Schreibweise vorliegt. sie widerspricht allen Konventionen, daher gilt diese Empfehlung nicht.
3. Schreiben Sie jetzt alles in Kleinbuchstaben (einschließlich Akronyme) und führen Sie dann einen der folgenden Schritte aus: <ph type="x-smartling-placeholder">
   </ph>
   • Das erste Zeichen jedes Wortes wird großgeschrieben, um die Pascal-Schreibweise zu erzeugen.
   • Das erste Zeichen jedes Worts wird großgeschrieben, mit Ausnahme des ersten CamelCase.
4. Zuletzt fassen Sie alle Wörter zu einer einzigen Kennung zusammen.

Die Groß- und Kleinschreibung der Wörter wird dabei fast vollständig ignoriert.

Formular	Richtig	Falsch
„XML-HTTP-Anfrage“	XmlHttpRequest	XMLHTTPRequest
„Neukunden-ID“	newCustomerId	newCustomerID
"innere stoppuhr"	innerStopwatch	innerStopWatch
„unterstützt IPv6 unter iOS“	supportsIpv6OnIos	supportsIPv6OnIOS
„YouTube-Importprogramm“	YouTubeImporter	YoutubeImporter*

(* Zulässig, aber nicht empfohlen.)

Dokumentation

Formatierung

Die grundlegende Formatierung von KDoc-Blöcken wird in diesem Beispiel gezeigt:

/**
 * Multiple lines of KDoc text are written here,
 * wrapped normally…
 */
fun method(arg: String) {
    // …
}

...oder in diesem einzeiligen Beispiel:

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

Die Standardform ist immer zulässig. Das einzeilige Formular kann Wird ersetzt, wenn der gesamte KDoc-Block (einschließlich Kommentarmarkierungen) ersetzt wird auf eine Linie passen. Dies gilt nur, wenn keine Tags wie @return blockieren.

Absätze

Eine Leerzeile, d. h. eine Zeile, die nur das ausgerichtete vorangestellte Sternchen enthält (*) wird zwischen den Absätzen und vor der Gruppe der Block-Tags (falls vorhanden) angezeigt.

Tags blockieren

Alle verwendeten standardmäßigen Block-Tags erscheinen in der Reihenfolge, @constructor, @receiver, @param, @property, @return @throws, @see, und diese werden nie ohne leere Beschreibung angezeigt. Wenn ein Block-Tag nicht in eine einzige Zeile passt, Fortsetzungszeilen sind um 4 Leerzeichen von der Position von @ entfernt.

Zusammenfassungsfragment

Jeder KDoc-Block beginnt mit einem kurzen Zusammenfassungsfragment. Dieses Fragment ist Dies ist der einzige Teil des Textes, der angezeigt wird, z. B. Klassen- und Methodenindexe.

Dies ist ein Fragment – eine Nominalphrase oder eine Verbphrase, kein vollständiger Satz. Er beginnt nicht mit "A `Foo` is a...", oder "This method returns...", noch muss es einen vollständigen Imperativsatz bilden wie „Save the record.“ Das Fragment ist jedoch großgeschrieben und wie ein vollständiger Satz.

Nutzung

KDoc ist mindestens für jeden public-Typ vorhanden, und jedes public- oder protected-Mitglied eines solchen Typs, mit den folgenden Ausnahmen.

Ausnahme: selbsterklärende Funktionen

KDoc ist für „einfache, offensichtliche“ Funktionen wie getFoo optional. und Properties wie foo angeben, wenn es wirklich nichts Nützliches gibt, außer „Gibt den foo zurück“.

Es ist nicht angemessen, diese Ausnahme zu nennen, um das Weglassen relevanter die ein typischer Leser wissen muss. Beispiel: eine Funktion mit dem Namen getCanonicalName oder eine Eigenschaft mit dem Namen canonicalName, die Dokumentation nicht wegzulassen (mit der Begründung, /** Returns the canonical name. */) angezeigt, wenn ein typischer Leser möglicherweise keine was der Begriff "kanonischer Name" bedeutet!

Ausnahme: Überschreibungen

KDoc ist nicht immer bei einer Methode vorhanden, die eine Supertyp-Methode überschreibt.