Kotlin stil kılavuzu

Bu dokümanda, Google'ın Kotlin Programlama Dili'ndeki kaynak kodu için Android kodlama standartlarının tam tanımı açıklanmaktadır. Bir Kotlin kaynak dosyası, yalnızca buradaki kurallara uyduğu takdirde Google Android Stili'nde olduğu için tanımlanır.

Diğer programlama stil kılavuzlarında olduğu gibi, ele alınan sorunlar sadece biçimlendirmeyle ilgili estetik sorunları değil, aynı zamanda diğer kural türlerini veya kodlama standartlarını da kapsıyor. Ancak bu belge, öncelikle evrensel olarak izlediğimiz katı ve değişmez kurallara odaklanmaktadır ve açıkça uygulanabilir olmayan (insan veya araç tarafından) tavsiyelerde bulunmaktan kaçınır.

Son güncelleme: 06.09.2023

Kaynak dosyalar

Tüm kaynak dosyalar UTF-8 olarak kodlanmalıdır.

Adlandırma

Kaynak dosyada yalnızca tek bir üst düzey sınıf varsa dosya adı büyük/küçük harfe duyarlı ad ile .kt uzantısını yansıtmalıdır. Aksi halde Kaynak dosya birden fazla üst düzey bildirim içeriyorsa bir ad seçin açıklamaya çalışın, PascalCase'ı (camelCase kabul edilebilir) ve .kt uzantısını ekleyin.

// 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() = // …

Özel Karakterler

Boşluk karakterleri

Satır sonlandırıcı dizisinin dışında, ASCII yatay boşluk karakteri (0x20) kaynak dosyada herhangi bir yerde görünen tek boşluk karakteridir. Bu, şu anlama gelir:

• Dize ve karakter değişmez değerlerindeki diğer tüm boşluk karakterleri atlanır.
• Sekme karakterleri girinti için kullanılmaz.

Özel kaçış dizileri

Özel bir kaçış dizisi olan tüm karakterler için (\b, \n, \r, \t, \', \", \\ ve \$), ilgili Unicode yerine bu sıranın kullanılması (ör. \u000a) kod dışı bırakılır.

ASCII olmayan karakterler

Kalan ASCII olmayan karakterler için gerçek Unicode karakteri (ör. ∞) veya eşdeğer Unicode çıkışı (ör. \u221e) kullanılır. Seçim, kodu yapan kişiye bağlıdır daha kolay okunup anlaşılır. Herhangi bir konumda yazdırılabilir karakterler için Unicode çıkışlarının kullanılması önerilmez. dize değişmez değerleri ve yorumları dışında kesinlikle önerilmez.

Örnek	Tartışma
val unitAbbrev = "μs"	En iyi: Yorum yapılmadan bile son derece nettir.
val unitAbbrev = "\u03bcs" // μs	Kötü: Yazdırılabilir bir karakterle çıkış karakterlerini kullanmak için hiçbir neden yoktur.
val unitAbbrev = "\u03bcs"	Kötü: Okuyucu, bunun ne olduğu hakkında bir fikri yoktu.
return "\ufeff" + content	İyi: Yazdırılamayan karakterler için çıkışlar kullanın ve gerekirse yorum yapın.

Yapı

.kt dosyası sırasıyla şu öğelerden oluşur:

• Telif hakkı ve/veya lisans başlığı (isteğe bağlı)
• Dosya düzeyinde ek açıklamalar
• Paket ekstresi
• İfadeleri içe aktar
• Üst düzey bildirimler

Bu bölümlerin her biri, tek bir boş satırla ayrılacaktır.

Telif Hakkı / Lisans

Dosyaya ait olan telif hakkı veya lisans başlığı, çok satırlı bir yorumun en üstüne yerleştirilmelidir.

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

KDoc stili kullanmayın veya tek satırlık bir yorum yazmak gibidir.

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

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

Dosya düzeyinde ek açıklamalar

"Dosya" içeren notlar use-site hedefi etiketleri, herhangi bir başlık yorumu ile paket bildirimi arasına yerleştirilir.

Paket ekstresi

Paket ifadesi, herhangi bir sütun sınırına tabi değildir ve hiçbir zaman satırla sarmalanmaz.

İfadeleri içe aktar

Sınıflara, işlevlere ve özelliklere ilişkin içe aktarma ifadeleri tek bir listede gruplandırılır ve ASCII olarak sıralanır.

Joker karakter içe aktarma işlemlerine (herhangi bir türde) izin verilmez.

Paket ifadesiyle benzer şekilde, içe aktarma ifadeleri sütun sınırı vardır ve hiçbir zaman satır kaydırılmazlar.

Üst düzey bildirimler

.kt dosyası bir veya daha fazla tür, işlev, özellik ya da tür bildirebilir takma adlar var.

Dosya içeriği tek bir temaya odaklanmalıdır. Buna örnekler herkese açık tek bir tür veya birden fazla alıcı türünde aynı işlemi yapmanıza olanak tanır. Alakasız beyanlar kendi dosyalarına ve kamuya açık beyanlarına göre tek bir dosyada ayrılmış olarak en aza indirilmelidir.

İçeriklerin sayısı veya sırası üzerinde açık bir kısıtlama uygulanmaz. olabilir.

Kaynak dosyalar genellikle yukarıdan aşağıya doğru okunur. Bu da, üst kısımlardaki beyannameler, bahsi geçen daha iyi anlamanızı sağlar. Farklı dosyalar sipariş edilebilir değişiklik gösterebilir. Benzer şekilde, bir dosyada 100 özellik bulunabilir, 10 işlev daha ve başka bir sınıf daha.

Önemli olan her bir dosyanın bir mantıksal sıralama kullanmasıdır. durumu açıklayabilir. Örneğin, yeni işlevler dosyanın sonuna eklenir. Bu da “kronolojik şeklinde bir sıralamaya ekleyebilirsiniz. Bu, mantıksal bir sıralama değildir.

Sınıf üyeleri sıralaması

Bir sınıftaki üyelerin sırası, üst düzey üyelerle aynı kurallara uyar beyanları.

Biçimlendirme

Diş telleri

when dallar ve if ifadeler için küme ayraçları gerekli değildir birden fazla else dalı olmayan ve tek bir satıra sığan.

if (string.isEmpty()) return

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

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

Bunun dışında herhangi bir if, for, when dalı, do, Gövde boş olduğunda veya yalnızca şunu içerse bile, while ifadeleri ve ifadeleri düşünebilirsiniz.

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

Boş olmayan bloklar

Semboller için Kernighan ve Ritchie tarzı ("Mısır parantezleri") kullanılır boş olmayan bloklar ve blok benzeri yapılar:

• Açılış parantezinden önce satır sonu yok.
• Açılış parantezinden sonra satır sonu.
• Kapanış ayracından önce satır sonu.
• Kapanış ayracından sonra satır sonu, yalnızca bu küme ayracı sona ererse ifadesi veya bir işlevin, kurucunun ya da adlandırılmış sınıfın gövdesini sonlandırır. Örneğin, arkasından şöyle satır geliyorsa küme parantezinden sonra satır sonu yok: else veya virgül.

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

Proje yöneticilerinin enum sınıfları aşağıda verilmiştir.

Boş bloklar

Boş blok veya blok benzeri bir yapı K&R tarzında olmalıdır.

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

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

İfadeler

İfade olarak kullanılan bir if/else koşulu küme ayraçlarını yalnızca tüm ifade bir satıra sığıyorsa atlayın.

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
}

Girinti

Yeni bir blok veya blok benzeri yapı her açıldığında girinti dört boşluk artar. Blok sona erdiğinde girinti önceki girinti düzeyine döner. Girinti düzeyi, blok boyunca hem kod hem de yorumlar için geçerlidir.

Her satıra bir ifade

Her ifadenin ardından bir satır sonu gelir. Noktalı virgül kullanılmaz.

Satır sarmalama

Kodun 100 karakterlik bir sütun sınırı vardır. Aşağıda belirtilenler dışında, bu sınırı aşacak tüm satırlar aşağıda açıklandığı gibi satıra sarmalanmalıdır.

İstisnalar:

• Sütun sınırına uymanın mümkün olmadığı satırlar (örneğin, KDoc'taki uzun bir URL)
• package ve import ekstreleri
• Bir yorumdaki kesilip kabuğa yapıştırılabilecek komut satırları

Nerelerde popülerlik yapılabilir?

Satır sarmalamanın ana yönergesi: daha yüksek söz dizimsel düzeyde kesmeyi tercih edin. Ayrıca:

• İşleç veya infix fonksiyon adında bir satır kırıldığında, operatör veya infix fonksiyon adından sonra gelir.
• Aşağıdaki "operatör benzeri" sembollerde bir çizgi kesildiğinde, sembolden önce gelir:
  • Nokta ayırıcı (., ?.).
  • Üye referansındaki iki iki nokta işareti (::).
• Bir yöntem veya kurucu adı, aynı işleve sahip açık paranteze (() ekli kalır o takip eder.
• Virgül (,), kendisinden önce gelen jetona ekli kalır.
• Lambda oku (->), kendisinden önceki bağımsız değişken listesine ekli kalıyor.

ziyaret edin.

Not: Satır kaydırmanın birincil hedefi kodun değil, net bir her zaman en az satıra sığdırır.

Fonksiyonlar

Bir işlev imzası tek bir satıra sığmadığında, her parametre bildirimini kendi satırına bölün. Bu biçimde tanımlanan parametrelerde tek bir girinti (+4) kullanılmalıdır. Kapanış parantezi ()) ve dönüş türü, ek girinti olmadan kendi satırına yerleştirilir.

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

İfade işlevleri

Bir fonksiyon tek bir ifade içerdiğinde ifade işlevine sahip olması gerekir.

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

override fun toString(): String = "Hey"

Özellikler

Özellik başlatıcı tek bir satıra sığmadığında, eşittir işaretinden (=) sonra girin ve bir girinti kullanın.

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

get ve/veya set işlevi bildiren özelliklerin her birini kendi satırında normal girinti (+4) ile gösterilir. Aynı kuralları kullanarak biçimlendirme ekleyebilirsiniz.

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

. Salt okunur özellikler, tek bir satıra sığan daha kısa bir söz dizimi kullanabilir.

val defaultExtension: String get() = "kt"

Boşluk

Sektör

Tek bir boş satır görünür:

• Bir sınıfın ardışık üyeleri arasında: özellikler, kurucular, fonksiyonlar, iç içe geçmiş sınıflar vb.
  • İstisna: İki arasında boş bir satır ardışık özellikler (aralarında başka kod olmadan) isteğe bağlıdır. Bu tür boş satırlar, mülkler ve ilişkili özelliklerin mantıksal gruplamaları kendi arka mülkleriyle (varsa) ilişkilendirebilir.
  • İstisna: Enum sabitleri arasındaki boş satırlar kapsam dahilindedir bölümüne göz atın.
• Kodu düzenlemek için gerektiğinde ifadeler arasında mantıksal alt bölümlere ayırır.
• İsteğe bağlı olarak, fonksiyondaki ilk ifadeden önce önce veya sınıftaki son üyeden sonra (ne teşvik ne de kırılmamalıdır).
• Bu belgenin diğer bölümlerinin ( Yapı bölümüne bakın).

Art arda birden fazla boş satıra izin verilir ancak kullanılması önerilmez veya gerek yoktur.

Yatay

Dil veya diğer stil kurallarının gerektirdiği yerlerde harflerden, yorumlardan ve KDoc'tan ayrı olarak, boşluk yalnızca aşağıdaki yerlerde görünür:

• if gibi ayrılmış kelimeleri ayırma, for veya catch gelen bir açık parantezden (() sonra açar.

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

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

• else veya catch, şuradan kapanış küme ayracı (}) ekleyin.

  // WRONG!
  }else {
  }
  

  // Okay
  } else {
  }
  

• Herhangi bir açık küme parantezinden önce ({).

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

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

• İkili sayı operatörünün her iki tarafında da.

  // WRONG!
  val two = 1+1
  

  .

  // Okay
  val two = 1 + 1
  

  Bu durum, aşağıdaki "operatör benzeri" simgeler için de geçerlidir:
  • lambda ifadesindeki ok (->).

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

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

  ziyaret edin. Ancak şunlar mümkün değil:
  • bir üye referansındaki iki iki nokta (::)

    // WRONG!
    val toString = Any :: toString
    

    // Okay
    val toString = Any::toString
    

  • nokta ayırıcı (.).

    // WRONG
    it . toString()
    

    // Okay
    it.toString()
    

  • aralık operatörü (..).

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

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

• İki nokta işaretinden (:) önce, yalnızca belirtmeye yönelik bir sınıf beyanında kullanılıyorsa temel sınıf veya arayüz ya da where ifadesinde kullanıldığında şunun için: genel kısıtlamalara tabidir.

  // 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>
  

• Virgül (,) veya iki nokta işaretinden (:) sonra.

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

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

  // WRONG!
  class Foo :Runnable
  

  // Okay
  class Foo : Runnable
  

• Eğik çizginin (//) her iki tarafında, satır sonu yorumu. Burada birden fazla boşluk kullanılabilir ancak zorunlu değildir.

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

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

Bu kural, hiçbir zaman teklif vermeyi zorunlu kılacak veya teklifte bulunmayacak şekilde yorumlanmaz satırın başında veya sonunda ek boşluk; yalnızca hedeflendiği için iç mekana sahip.

Belirli yapılar

Sıralama sınıfları

İşlevsiz ve sabit değerleriyle ilgili belge içermeyen bir enum isteğe bağlı olarak tek satır olarak biçimlendirilebilir.

enum class Answer { YES, NO, MAYBE }

Sıralamadaki sabit değerler ayrı satırlara yerleştirildiğinde, gövde tanımladığı durumlar dışında bunların arasında boş bir satır olması gerekmez.

enum class Answer {
    YES,
    NO,

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

Sıralama sınıfları sınıf olduğundan biçimlendirme sınıflarına ilişkin diğer tüm kurallar geçerlidir.

Ek Açıklamalar

Üye veya tür ek açıklamaları, ek açıklamalı yapıdan hemen önce ayrı satırlara yerleştirilir.

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

Bağımsız değişken içermeyen notlar tek bir satıra yerleştirilebilir.

@JvmField @Volatile
var disposable: Disposable? = null

Bağımsız değişkeni olmayan tek bir ek açıklama varsa beyan ile aynı satıra yerleştirilebilir.

@Volatile var disposable: Disposable? = null

@Test fun selectAll() {
    // …
}

@[...] söz dizimi yalnızca açık bir site kullanımı hedefiyle ve yalnızca 2 veya daha fazla ek açıklamayı bağımsız değişken olmadan tek bir satırda birleştirme.

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

Örtülü iade/mülk türleri

Bir ifade işlevi gövdesi veya özellik başlatıcı skaler ise değeri veya dönüş türü, gövdeden açıkça çıkarılabildiği için atlanabilir.

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")

Kitaplık yazarken açık tür bildirimini koruyun: genel API'nin bir parçasıdır.

Adlandırma

Tanımlayıcılar yalnızca ASCII harfler ve rakamlar ile aşağıda belirtilen az sayıda durumda alt çizgi kullanır. Bu nedenle, her geçerli tanımlayıcı adı \w+ normal ifadesiyle eşleştirilir.

Örneklerde görülenlere benzer özel ön ekler veya son ekler name_, mName, s_name ve kName, şu durumlar dışında kullanılmaz: özellikleri (bkz. Mülkleri destekleme).

Paket Adları

Paket adlarının tümü küçük harfle yazılır ve ardışık kelimeler basitçe kullanılır birleştirilmiş (alt çizgi olmadan).

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

Tür adları

Sınıf adları, PascalCase ile yazılır ve genellikle isimlerden veya isimlerden oluşur. anlamına gelir. Örneğin, Character veya ImmutableList. Arayüz adları aynı zamanda adlar veya isimlerden oluşan ifadeler de (örneğin, List) olabilir, ancak bazen sıfatlar veya sıfat ifadeler olabilir (örneğin, Readable).

Test sınıfları, test ettikleri sınıfın adından başlayarak adlandırılır. ve Test ile bitiyor. Örneğin, HashTest veya HashIntegrationTest.

İşlev adları

İşlev adları büyük harfle yazılır ve genellikle fiil veya fiil kelime öbeklerinden oluşur. Örneğin, sendMessage veya stop.

Test işlevi adlarında, adın mantıksal bileşenlerini ayırmak için alt çizgi karakterlerinin kullanılmasına izin verilir.

@Test fun pop_emptyStack() {
    // …
}

Unit döndüren ve @Composable ile açıklama eklenen işlevler PascalCased'dir ve tür gibi isim olarak adlandırılır.

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

İşlev adları boşluk içermemelidir, çünkü bu özellik tüm platformunda (özellikle de Android'de tam olarak desteklenmemektedir).

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

Sabit adlar

Sabit adlarda UPPER_SNAKE_CASE kullanılır: tümü büyük harf, içeren bir liste oluşturabilirsiniz. Peki sabit değer tam olarak nedir?

Sabitler, özel get işlevi olmayan ve içerikleri şu şekilde olan val özellikleridir: kalıcı olarak değişmez ve işlevlerinin yan etkiye sahip olmaması gerekir. Bu sabit türler ve sabit tür koleksiyonları içerir. const olarak işaretlenirse skalerler ve dizeler de gösterilir. Örneklerden herhangi biri gözlemlenebilir durum değişebilir, sabit değildir. Yalnızca hiçbir zaman değiştirmeyin.

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

Bu adlar genellikle isimler veya isimlerden oluşur.

Sabit değerler yalnızca object içinde tanımlanabilir üst düzey bir bildirim olarak kabul edebilirsiniz. Bir sabit olmayan ancak class içinde tanımlanan bir ad sabit olmayan bir ad kullanmalıdır.

Skaler değer olan sabitler const kullanmalıdır. değiştirici.

Sabit olmayan adlar

Sabit olmayan adlar büyük/küçük harf düzeniyle yazılır. Bunlar örnek özellikleri, yerel özellikler ve parametre adları için geçerlidir.

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")

Bu adlar genellikle isimler veya isimlerden oluşur.

Mülkler yedekleniyor

Bir destek mülkü adı, gayrimenkulün adı ile tam olarak aynı olmalıdır. dışında bir alt çizgi kullanılamaz.

private var _table: Map? = null

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

Değişken adlarını yazın

Her tür değişkeni iki stilden birinde adlandırılır:

• İsteğe bağlı olarak tek bir büyük harf ve ardından tek rakam (ör. E, T, X, T2)
• Sınıflar için kullanılan biçimde bir ad ve ardından büyük harf kullanımı T harfi (ör. RequestT, FooBarT)

Deve kılıfı

Bazen İngilizce bir kelime öbeğini büyük/küçük harfe dönüştürmenin birden fazla makul yolu vardır. Örneğin, kısaltmalar veya "IPv6" ya da "iOS" gibi alışılmadık yapılar mevcut olduğunda. Tahmin edilebilirliği iyileştirmek için aşağıdaki şemayı kullanın.

Adın düz yazı biçimiyle başlayın:

1. Kelime öbeğini düz ASCII'ye dönüştürün ve tüm kesme işaretlerini kaldırın. Örneğin, "Müller'in algoritması", "Müleller algoritması" olabilir.
2. Bu sonucu, boşluk ve kalan noktalama işaretlerine (genellikle tire) göre ayırarak kelimelere bölün. Önerilen: Herhangi bir kelime yaygın olarak kullanılan bir deve harfi haline gelmişse bunu oluşturan bileşenlere bölün (ör. “AdWords”, “reklam kelimeleri” haline gelir). "iOS" gibi bir kelimenin aslında tek başına büyük ve küçük harflerden ibaret olmadığını unutmayın; herhangi bir kurallara aykırı olduğu için bu öneri geçerli değil.
3. Şimdi, her şeyi küçük harfle (kısaltmalar dahil) yapın, ardından aşağıdakilerden birini yapın:
   • Pascal büyük harf oluşturmak için her kelimenin ilk karakterini büyük yapın.
   • Elde edilen ilk karakter hariç her kelimenin ilk karakterini büyük harf yap büyük/küçük harfe duyarlıdır.
4. Son olarak, tüm kelimeleri tek bir tanımlayıcıda birleştirin.

Orijinal kelimelerdeki büyük/küçük harf düzeninin neredeyse hiç dikkate alınmadığına dikkat edin.

Düzyazı biçimi	Doğru	Yanlış
"XML Http İsteği"	XmlHttpRequest	XMLHTTPRequest
"yeni müşteri kimliği"	newCustomerId	newCustomerID
"dahili kronometre"	innerStopwatch	innerStopWatch
"iOS'te IPv6'yı destekler"	supportsIpv6OnIos	supportsIPv6OnIOS
"YouTube içe aktarıcısı"	YouTubeImporter	YoutubeImporter*

(* Kabul edilebilir ancak önerilmez.)

Not: İngilizcede bazı kelimeler belirsiz bir şekilde kısa çizgiyle çevrilir: Örneğin "boş olmayan" ve "boş olmayan" seçenekleri doğru olduğundan yöntem adları checkNonempty ve checkNonEmpty benzer şekilde doğrudur.

Belgeler

Biçimlendirme

KDoc bloklarının temel biçimlendirmesi şu örnekte gösterilmiştir:

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

...veya şu tek satırlık örnekte:

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

Temel biçim her zaman kabul edilir. Tek satırlı form KDoc bloğunun tamamı (yorum işaretçileri dahil) olduğunda değiştirilir tek bir satıra sığabilir. Bunun yalnızca @return gibi blok etiketleri engeller.

Paragraf

Tek boş satır; yani yalnızca başında hizalı yıldız işareti içeren bir satır (*)—Paragraflar arasında ve varsa blok etiketleri grubundan önce görünür.

Etiketleri engelle

Kullanılan standart "engelleme etiketlerinin" herhangi biri @constructor, @receiver, @param, @property, @return, @throws, @see ve bunlar hiçbir zaman boş bir açıklamayla görünmez. Bir engelleme etiketi tek bir satıra sığmadığında, devam çizgileri, @ konumundan 4 boşluk girintilidir.

Özet parçası

Her KDoc bloğu kısa bir özet parçasıyla başlar. Bu parça çok önemlidir: metinde görünen tek bölümdür bazı bağlamlarda (ör. sınıf ve yöntem dizinleri) kullanılabilir.

Bu, tam bir cümle değil, bir parça (ad) kelime öbeği veya fiil ifadesidir. "A `Foo` is a..." ile başlamıyor, veya "This method returns...", zorunluluk içeren bir cümle oluşturmadığı veya "Save the record.". Ancak, parça büyük harfle yazılmıştır ve tam bir cümleymiş gibi noktalama işaretleri var.

Kullanım

KDoc, en azından her public türü için mevcuttur. ve bu türdeki her public veya protected üye için aşağıda belirtilen birkaç istisna ile uyumludur.

İstisna: Kendini açıklayan fonksiyonlar

KDoc, getFoo gibi "basit, bariz" işlevler için isteğe bağlıdır ve foo gibi mülklerde gösterilebilir.

Bu istisnanın, alakalı bir kaydın atlanmasını haklı çıkarmak için kullanılması uygun değildir standart bir okuyucunun bilmesi gereken bilgiler arasında yer alır. Örneğin, getCanonicalName adlı bir işlev veya canonicalName adlı bir özellik, belgeyi atlamayın (bunların mantığından dolayı, belgenin /** Returns the canonical name. */) genel bir okuyucuda "kurallı ad" teriminin ne olduğu anlamına geliyor!

İstisna: geçersiz kılmalar

KDoc, bir süper tür yöntemini geçersiz kılan bir yöntemde her zaman mevcut değildir.