Kotlin stil kılavuzu

Bu belge, Google'ın Kotlin Programlama Dili'nde kaynak koda yönelik Android kodlama standartlarının tam tanımıdır. Bir Kotlin kaynak dosyasının, yalnızca buradaki kurallara uyması halinde Google Android Stili'nde olduğu kabul edilir.

Diğer programlama stili kılavuzları gibi, ele alınan konular yalnızca estetik biçimlendirme sorunlarını değil, diğer kural türlerini veya kodlama standartlarını da kapsar. Ancak, bu belge esas olarak evrensel olarak uyguladığımız kesin ve hızlı kurallara odaklanmaktadır ve açıkça uygulanabilir olmayan (insan veya araç tarafından) tavsiyeler vermekten kaçınır.

Son güncelleme: 06.09.2023

Kaynak dosyalar

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

Adlandırma

Kaynak dosya yalnızca tek bir üst düzey sınıf içeriyorsa dosya adı, büyük/küçük harfe duyarlı adı ve .kt uzantısını yansıtmalıdır. Aksi takdirde, bir kaynak dosyada birden çok üst düzey bildirim varsa dosyanın içeriğini tanımlayan bir ad seçin, PascalCase'i (dosya adı çoğulsa CamelCase kabul edilebilir) uygulayın 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ı sırası dışında, kaynak dosyanın herhangi bir yerinde görünen tek boşluk karakteri ASCII yatay boşluk karakteri (0x20) şeklindedir. Bunun anlamı şudur:

• Dize ve karakter sabit değerlerindeki diğer tüm boşluk karakterlerine çıkış yapılır.
• Girinti için sekme karakterleri kullanılmaz.

Özel kaçış dizileri

Özel bir kaçış dizisi olan tüm karakterler (\b, \n, \r, \t, \', \", \\ ve \$) için karşılık gelen Unicode (ör. \u000a) kod dışı bırakın.

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. Yapacağınız seçim yalnızca kodun hangi kodun daha kolay okunup anlaşıldığına bağlıdır. Unicode çıkışları, herhangi bir konumda yazdırılabilir karakterler için önerilmez ve dize değişmez değerleri ve yorumları dışında kesinlikle önerilmez.

Örnek	Tartışma
val unitAbbrev = "μs"	En iyi: Yorum yapmasa bile tamamen anlaşılır.
val unitAbbrev = "\u03bcs" // μs	Kötü: Yazdırılabilir bir karakter içeren kaçış karakteri kullanmak için hiçbir neden yoktur.
val unitAbbrev = "\u03bcs"	Kötü: Okuyucunun bunun ne olduğunu bilmiyor.
return "\ufeff" + content	İyi: Yazdırılamayan karakterler için çıkış karakterleri kullanın ve gerekiyorsa yorum yapın.

Yapı

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

• Telif hakkı ve/veya lisans başlığı (isteğe bağlı)
• Dosya düzeyinde ek açıklamalar
• Paket özeti
• Ekstreleri içe aktar
• Üst düzey beyanlar

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

Telif Hakkı / Lisans

Bir telif hakkı veya lisans başlığı dosyaya aitse çok satırlı yorumun hemen en üstüne yerleştirilmelidir.

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

KDoc stili veya tek satır stili bir yorum kullanmayın.

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

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

Dosya düzeyinde ek açıklamalar

"file" use-site target değerine sahip ek açıklamalar, herhangi bir başlık yorumu ile paket bildirimi arasına yerleştirilir.

Paket özeti

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

Ekstreleri içe aktar

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

Joker karakter içe aktarmalarına (herhangi bir türde) izin verilmez.

Paket ifadesine benzer şekilde, içe aktarma ifadeleri de bir sütun sınırına tabi değildir ve hiçbir zaman satıra sarmalanmaz.

Üst düzey beyanlar

Bir .kt dosyası, üst düzeyde bir veya daha fazla tür, işlev, özellik ya da tür takma adı tanımlayabilir.

Bir dosyanın içeriği tek bir temaya odaklanmalıdır. Buna örnek olarak tek bir herkese açık tür veya birden fazla alıcı türünde aynı işlemi gerçekleştiren bir dizi uzantı işlevi verilebilir. İlgili olmayan bildirimler kendi dosyalarına ayrılmalıdır ve tek bir dosya içindeki herkese açık bildirimler en aza indirilmelidir.

Dosya içeriklerinin sayısı veya sırası üzerinde açık bir kısıtlama bulunmaz.

Kaynak dosyalar genellikle yukarıdan aşağıya doğru okunur. Yani, sıralama, genel olarak, daha yukarıdaki beyanların, daha aşağıda bulunanların anlaşılmasına yardımcı olacağını yansıtır. Farklı dosyalar, içeriklerini farklı şekilde sıralamayı tercih edebilir. Benzer şekilde, bir dosya 100 özellik, başka bir 10 işlev ve bir başkası da tek bir sınıf içerebilir.

Önemli olan, her dosyanın bazı mantıksal sıralar kullanmasıdır. Mantıksal sıralama kullanılırsa bunu ana yardımcısı açıklayabilir. Örneğin, yeni işlevler yalnızca dosyanın sonuna alışkanlık olarak eklenmiyor, çünkü bu, mantıksal bir sıralama olmayan "eklenme tarihine göre kronolojik" sıralamaya yol açacaktır.

Sınıf üyesi sıralama

Bir sınıf içindeki üyelerin sırası, üst düzey bildirimlerle aynı kurallara uyar.

Biçimlendirme

Diş telleri

Birden fazla else dalı bulunmayan ve tek bir satıra sığan when dalları ve if ifadeleri için küme parantezi gerekli değildir.

if (string.isEmpty()) return

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

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

Gövde boş olsa veya yalnızca tek bir ifade içerse bile tüm if, for, when dalı, do ve while ifadeleri ve ifadeleri için parantez kullanılması gerekir.

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

Dişli ayraçlar, boş olmayan bloklar ve blok benzeri yapılar için Kernighan ve Ritchie stilini ("Mısır parantezleri") izler:

• Açılış küme ayracından önce satır sonu yok.
• Açılış ayraçlarından sonra satır sonu.
• Kapanış parantezinden önce satır sonu.
• Kapanış parantezinden sonra satır sonu. Yalnızca bu küme parantezi bir ifadeyi sona erdirirse ya da işlevin, kurucunun veya adlandırılmış sınıfın gövdesini sonlandırırsa. Örneğin, süslü ayraçtan sonra else veya virgül gelirse satır arası yok.

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

Aşağıda enum sınıfları için birkaç istisna verilmiştir.

Boş bloklar

Boş blok veya blok benzeri yapı K&R stilinde 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, yalnızca ifadenin tamamı bir satıra sığıyorsa süslü ayraçları atlayabilir.

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 bir yapı açıldığında, girinti dört boşluk artar. Blok sona erdiğinde, girinti önceki girinti düzeyine geri 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 kaydırma

Kodun sütun sınırı 100 karakterdir. Aşağıda belirtilen durumlar dışında, bu sınırı aşacak tüm satırlar aşağıda açıklandığı gibi satır sarmalanmalıdır.

İstisnalar:

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

Nerelerde kırılır?

Satır sarmalamanın ana yönergesi şudur: Daha yüksek bir söz dizimi seviyesinde bölmeyi tercih etmek. Ayrıca:

• Bir satır, bir operatör veya infix işlevi adında kesildiğinde bu ara, operatör veya infix işlevi adından sonra gelir.
• Aşağıdaki "operatör benzeri" simgelerde bir çizgi kesildiğinde ara, simgeden önce gelir:
  • Nokta ayırıcı (., ?.).
  • Bir üye referansının iki nokta işareti (::).
• Yöntem veya kurucu adı, kendisinden sonra gelen açık paranteze (() ekli kalır.
• Virgül (,), önündeki jetona ekli kalır.
• Lambda oku (->), kendisinden önce gelen bağımsız değişken listesine ekli kalır.

İşlevler

İşlev imzası tek bir satıra sığmadığında her parametre bildirimini kendi satırına bölün. Bu biçimde tanımlanan parametreler tek bir girinti (+4) kullanmalı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 işlev yalnızca tek bir ifade içerdiğinde ifade işlevi olarak temsil edilebilir.

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

override fun toString(): String = "Hey"

Özellikler

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

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

get ve/veya set işlevi tanımlayan özellikler, her birini normal girintiyle (+4) kendi satırına yerleştirmelidir. Bunları, aynı kuralları kullanarak işlevlerle biçimlendirin.

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:

• Sınıfın ardışık üyeleri arasında: mülkler, kurucular, işlevler, iç içe yerleştirilmiş sınıflar vb.
  • İstisna: İki ardışık özellik arasında boş bir satır olması (aralarında başka bir kod olmaması) isteğe bağlıdır. Bu tür boş satırlar, özelliklerin mantıksal gruplamalarını oluşturmak ve varsa, özellikleri destek mülkleriyle ilişkilendirmek için gerektiğinde kullanılır.
  • İstisna: Enum sabitleri arasındaki boş satırlar aşağıda ele alınmıştır.
• Kodu mantıksal alt bölümler halinde düzenlemek için gerektiğinde ifadeler arasında.
• İsteğe bağlı olarak bir işlevin ilk ifadeden önce, bir sınıfın ilk üyesinden önce veya bir sınıfın son üyesinden sonra (ne teşvik edilir ne de teşvik edilmez).
• Bu belgenin diğer bölümlerinin gerektirdiği şekilde ( Yapı bölümü gibi).

Art arda birden fazla boş satıra izin verilir, ancak bunlar teşvik edilmez veya hiçbir zaman zorunlu tutulmaz.

Yatay

Dil veya diğer stil kurallarının gerektirdiği durumlarda, harfler, yorumlar ve KDoc'un dışında tek bir ASCII alanı yalnızca aşağıdaki yerlerde görünür:

• if, for veya catch gibi ayrılmış kelimeleri bu satırda izleyen açık parantezden (() ayırma.

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

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

• else veya catch gibi ayrılmış kelimeleri bu satırda başındaki kapanış parantezinden (}) ayırma.

  // WRONG!
  }else {
  }
  

  // Okay
  } else {
  }
  

• Açık küme parantezinden ({) önce.

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

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

• Herhangi bir ikili operatörün her iki tarafında da bulunur.

  // 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 işaretini kaldırın.

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

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

  Ancak şunlar geçerli değildir:
  • bir üye referansının iki adet iki nokta üst üste işareti (::).

    // WRONG!
    val toString = Any :: toString
    

    // Okay
    val toString = Any::toString
    

  • nokta ayırıcıyı (.) kullanın.

    // 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 üst üste işareti (:) yalnızca temel sınıf veya arayüzleri belirtmek için bir sınıf bildiriminde kullanıldığında ya da genel kısıtlamalar için where ifadesinde kullanıldığında.

  // 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 üst üste işaretinden (:) sonra.

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

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

  // WRONG!
  class Foo :Runnable
  

  // Okay
  class Foo : Runnable
  

• Satır sonu yorumunu başlatan çift eğik çizginin (//) her iki tarafında da. 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 bir satırın başında veya sonunda ek boşluk gerektirmek veya vermekten ibaret olarak yorumlanmaz; yalnızca iç alanı ele alır.

Belirli yapılar

Enum sınıfları

İşlevi olmayan ve sabit değerlerinde belge içermeyen bir enum, isteğe bağlı olarak tek satır olarak biçimlendirilebilir.

enum class Answer { YES, NO, MAYBE }

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

enum class Answer {
    YES,
    NO,

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

Enum sınıfları sınıf olduğundan, biçimlendirme sınıflarına yönelik 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 ek açıklamalar tek bir satıra yerleştirilebilir.

@JvmField @Volatile
var disposable: Disposable? = null

Bağımsız değişken içermeyen tek bir ek açıklama bulunduğunda bu ek açıklama, bildirimle aynı satıra yerleştirilebilir.

@Volatile var disposable: Disposable? = null

@Test fun selectAll() {
    // …
}

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

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

Dolaylı iade/mülk türleri

Bir ifade işlevi gövdesi veya özellik başlatıcısı skaler bir değerse ya da döndürme türü gövdeden net bir şekilde çıkarılabiliyorsa bu değer çıkarılabilir.

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, genel API'nin parçası olduğunda saklayın.

Adlandırma

Tanımlayıcılar yalnızca ASCII harfleri ve rakamların yanı sıra aşağıda belirtilen bazı durumlarda alt çizgi kullanır. Dolayısıyla, her geçerli tanımlayıcı adı \w+ normal ifadesiyle eşleştirilir.

name_, mName, s_name ve kName örneklerinde görülenler gibi özel önekler veya sonekler, yedekleme özellikleri durumu dışında kullanılmaz (bkz. Yedekleme özellikleri).

Paket Adları

Paket adlarının tümü küçük harfle yazılır ve ardışık kelimeler birbirine eklenir (alt çizgi olmadan).

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

Adları yazın

Sınıf adları PascalCase ile yazılır ve genellikle isimlerden veya isim kelime öbeklerinden oluşur. Örneğin, Character veya ImmutableList. Arayüz adları, ad veya isim kelime öbekleri (örneğin, List) olabilir ancak bazen sıfat veya sıfat ifadelerinden de oluşabilir (örneğin Readable).

Test sınıfları, test ettikleri sınıfın adından başlanarak Test ile biter. Örneğin, HashTest veya HashIntegrationTest.

İşlev adları

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

Adın mantıksal bileşenlerini ayırmak için test işlevi adlarında alt çizgi kullanılmasına izin verilir.

@Test fun pop_emptyStack() {
    // …
}

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

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

İşlev adları boşluk içermemelidir çünkü bu özellik her platformda desteklenmez (özellikle Android'de tam olarak desteklenmez).

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

Sabit adlar

Sabit adlarda UPPER_SNAKE_CASE kullanılır: Tüm kelimeler büyük harflerden oluşur ve kelimeler alt çizgiyle ayrılır. Peki sabit değer nedir tam olarak?

Sabitler, özel get işlevi olmayan, içerikleri son derece sabit olan ve işlevlerinin algılanabilir yan etkisi olmayan val özellikleridir. Sabit türler ve sabit türlerden oluşan sabit koleksiyonların yanı sıra const olarak işaretlenen skaler ve dizeleri de içerir. Bir örneğin gözlemlenebilir durumundan herhangi biri değişebiliyorsa bu değer sabit değildir. Nesneyi asla değiştirmemek yeterli değildir.

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 isimlerden veya isim kelime öbeklerinden oluşur.

Sabit değerler yalnızca bir object içinde veya üst düzey bildirim olarak tanımlanabilir. Aksi takdirde sabit değer gereksinimini karşılayan ancak class içinde tanımlanan değerler sabit olmayan bir ad kullanmalıdır.

Skaler değerler olan sabit değerler, const değiştiriciyi kullanmalıdır.

Sabit olmayan adlar

Sabit olmayan adlar büyük/küçük harf durumunda 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 isimlerden veya isim kelime öbeklerinden oluşur.

Özellikleri destekleme

Yedekleme özelliği gerektiğinde, özelliğin adı alt çizgiyle öne çıkarılmadıkça gerçek mülkün adıyla tam olarak eşleşmelidir.

private var _table: Map? = null

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

Değişken adları 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 bir sayı gelmelidir (ör. E, T, X, T2)
• Sınıflar için kullanılan biçimde bir ad ve büyük harfle başlayan T (ör. RequestT, FooBarT)

Deve kılıfı

Bazen kısaltmalar ya da "IPv6" veya "iOS" gibi alışılmadık yapılar olması gibi İngilizce bir ifadeyi deveye dönüştürmenin birden fazla makul yolu vardır. Öngörülebilirliği iyileştirmek için aşağıdaki şemayı kullanın.

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

1. Kelime öbeğini düz ASCII'ye dönüştürün ve kesme işaretlerini kaldırın. Örneğin, "Müller algoritması" "Müller algoritması" haline gelebilir.
2. Bu sonucu kelimelere bölün, boşluklara ve kalan noktalama işaretlerine (genellikle kısa çizgi) bölün. Önerilen: Yaygın olarak kullanılan geleneksel deve ağacı görünümüne sahip bir kelime varsa bunu bileşenlerine (ör. "AdWords", "reklam kelimeleri" haline gelir.") "iOS" gibi bir kelimenin aslında büyük/küçük harf kullanımı için uygun olmadığını, her kurala uygun olmadığını ve dolayısıyla bu önerinin geçerli olmadığını unutmayın.
3. Şimdi her şeyi (kısaltmalar dahil) küçük harfle yazın ve aşağıdakilerden birini yapın:
   • Pascal değerinin büyük olması için her kelimenin ilk karakterini büyük harfle yazın.
   • Deveye dönüşen ilk kelime hariç, her kelimenin ilk karakterini büyük harfle yazın.
4. Son olarak, tüm kelimeleri tek bir tanımlayıcıda birleştirin.

Orijinal kelimelerin büyük/küçük harf kullanımının neredeyse tamamen dikkate alınmadığını unutmayın.

Düzey formu	Doğru	Yanlış
"XML Http İsteği"	XmlHttpRequest	XMLHTTPRequest
"yeni müşteri kimliği"	newCustomerId	newCustomerID
"iç kronometre"	innerStopwatch	innerStopWatch
"iOS'te IPv6'yı destekler"	supportsIpv6OnIos	supportsIPv6OnIOS
"YouTube içeri aktarma aracı"	YouTubeImporter	YoutubeImporter*

(* Kabul edilebilir ancak önerilmez.)

Belgeler

Biçimlendirme

KDoc bloklarının temel biçimlendirmesi aşağıdaki örnekte gösterilmiştir:

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

...veya bu tek satırlık örnekte:

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

Temel biçim her zaman kabul edilir. KDoc bloğunun tamamı (yorum işaretçileri dahil) tek bir satıra sığdığında tek satırlı biçim değiştirilebilir. Bunun yalnızca @return gibi engelleme etiketi olmadığında geçerli olduğunu unutmayın.

Paragraflar

Boş bir satır, yani yalnızca başında hizalı yıldız işaretini (*) içeren bir satır, paragraflar arasında ve varsa blok etiketleri grubundan önce görünür.

Etiketleri engelle

Kullanılan standart "engelleme etiketleri" @constructor, @receiver, @param, @property, @return, @throws, @see sırasında görünür ve bunlar hiçbir zaman boş bir açıklamayla görünmez. Bir blok etiketi tek bir satıra sığmazsa devam satırları @ konumundan 4 boşluk girintili olarak yapılır.

Özet bölümü

Her KDoc bloğu, kısa bir özet parçasıyla başlar. Bu parça çok önemlidir: Sınıf ve yöntem dizinleri gibi belirli bağlamlarda görünen metnin tek bölümüdür.

Bu, tam bir cümle değil, parça anlamına gelir. Bir isim ifadesi veya fiil ifadesidir. "A `Foo` is a..." veya "This method returns..." ile başlamaz ve "Save the record." gibi tam bir zorunlu cümlesi oluşturması da gerekmez. Bununla birlikte, parçada büyük harfle ve tam bir cümleymiş gibi noktalama işareti kullanılır.

Kullanım

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

İstisna: Kendini açıklayan işlevler

KDoc, getFoo gibi "basit, bariz" işlevler ve foo gibi özellikler için isteğe bağlıdır. Bu durumlarda, "foo'yu döndürür"den başka bir şey söylenmeye değmez.

Tipik bir okuyucunun bilmesi gereken alakalı bilgilerin verilmemesi için bu istisnadan alıntı yapmak uygun değildir. Örneğin, tipik bir okuyucunun "standart ad" teriminin ne anlama geldiği hakkında hiçbir fikri yoksa getCanonicalName adlı işlev veya canonicalName adlı özellik için dokümanlarını (sadece /** Returns the canonical name. */ denmesini gerekçeyle) ihmal etmeyin.

İstisna: geçersiz kılmalar

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