Kotlin stil kılavuzu

Bu belge, Kotlin Programlama Dilinde kaynak koda yönelik Google'ın Android kodlama standartlarının tam tanımını sağlamaktadır. Kotlin kaynak dosyası, yalnızca buradaki kurallara uygun olduğu takdirde Google Android Stili'nde olarak tanımlanır.

Diğer programlama stili kılavuzları gibi, ele alınan konular yalnızca biçimlendirmeyle ilgili estetik konuları 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 kısa kurallara odaklanmaktadır ve (hem gerçek kişiler hem de araçlar tarafından) açıkça uygulanabilir olmayan 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 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, kaynak dosyada birden çok üst düzey bildirim varsa dosyanın içeriğini açıklayan bir ad seçin, PascalCase'i uygulayın (dosya adı çoğulsa 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ı dizisinden ayrı olarak, kaynak dosyanın herhangi bir yerinde görünen tek boşluk karakteri ASCII yatay boşluk karakteri (0x20)'dir. Bunun anlamı şudur:

  • Dize ve karakter değişmez değerlerindeki diğer tüm boşluk karakterleri kod dışı bırakılır.
  • Girinti için sekme karakterleri kullanılmaz.

Özel kaçış dizileri

Özel bir kaçış dizisine sahip herhangi bir karakter için (\b, \n, \r, \t, \', \", \\ ve \$) karşılık gelen Unicode (ör. \u000a) kod dışı bırakın.

ASCII olmayan karakterler

Geri kalan ASCII olmayan karakterler için ya gerçek Unicode karakteri (ör. ) veya eşdeğer bir Unicode çıkışı (ör. \u221e) kullanılır. Yapacağınız seçim, yalnızca hangi yöntemin kodu okumayı ve anlamayı daha kolay hale getirdiğine bağlıdır. Unicode çıkışları, herhangi bir konumdaki 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 yazmasa bile son derece nettir.
val unitAbbrev = "\u03bcs" // μs Kötü: Yazdırılabilir bir karakter kullanarak kaçış karakteri kullanmak için hiçbir sebep yoktur.
val unitAbbrev = "\u03bcs" Kötü: Okuyucunun bunun ne olduğuna dair hiçbir fikri yok.
return "\ufeff" + content İyi: Yazdırılamayan karakterler için çıkış 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
  • İfadeleri içe aktarın
  • Üst düzey beyanlar

Bu bölümlerin her birini tam olarak bir boş satır ayırır.

Dosyada bir telif hakkı veya lisans başlığı varsa üstbilgi, çok satırlı yorumun hemen en üstüne yerleştirilmelidir.

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

KDoc stili veya tek satırlık stilde yorum kullanmayın.

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

Dosya düzeyinde ek açıklamalar

"file" use-site target içeren notlar, 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.

İfadeleri içe aktarın

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

Hiçbir türde joker karakter içe aktarmaya izin verilmez.

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

Üst düzey beyanlar

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

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

Dosyalardaki içeriklerin sayısı veya sırası üzerinde açık bir kısıtlama uygulanmaz.

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ıtmalıdır. Farklı dosyalar, içeriklerini farklı şekilde sıralamayı tercih edebilir. Benzer şekilde, bir dosya 100 özellik, başka bir 10 işlev ve başka bir dosya da tek bir sınıf içerebilir.

Önemli olan, her dosyanın bir mantıksal sıra kullanmasıdır. İstendiğinde dosyanın sorumlusu bunu açıklayabilir. Örneğin, yeni işlevler sadece dosyanın sonuna düzenli olarak eklenmez, çünkü bu durumda "eklenme tarihine göre kronolojik" bir sıralama elde edilir, bu da mantıksal bir sıralama değildir.

Sınıf üyesi sıralaması

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

Biçimlendirme

Diş telleri

En fazla bir else dalı olan ve tek bir satıra sığan when dalları ve if ifadeleri için süslü ayraçlar 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 parantezler 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ış küme ayracından sonra satır sonu.
  • Kapanış parantezinden önce satır sonu.
  • Kapanış parantezinden sonra satır sonu. Yalnızca bu parantez bir ifadeyi sonlandırıyorsa veya bir işlevin, kurucunun veya adlandırılmış sınıfının gövdesini sonlandırıyorsa. Örneğin, başında else veya virgül varsa küme parantezinden sonra no satır sonu olmaz.
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ş bir 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 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, bloktaki 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ılmamalıdır.

Satır kaydırma

Kodun sütun sınırı 100 karakterdir. Aşağıda belirtilenler dışında, bu sınırı aşacak tüm satırlar aşağıda açıklandığı gibi satırla 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
  • Yorumdaki, kesilip kabuğa yapıştırılabilen komut satırları

Nerede mola verilir?

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

  • Bir operatör veya infix işlev adında bir satır kırıldığında ara, operatör veya infix işlev adından sonra gelir.
  • Aşağıdaki "operatör benzeri" simgelerde bir çizgi kırıldığında, sembolden önce ara gelir:
    • Nokta ayırıcı (., ?.).
    • Üye referansının iki nokta üst üste işareti (::).
  • Yöntem veya kurucu adı, kendisinden sonra gelen açık paranteze (() ekli kalır.
  • Virgül (,), kendisinden önce gelen jetona ekli kalır.
  • Lambda oku (->), kendisinden önce gelen bağımsız değişken listesine ekli kalı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 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"

Kod

Bir özellik başlatıcı 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 mülkler, her birini normal bir 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

Dikey

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

  • Sınıfın ardışık üyeleri arasında: özellikler, kurucular, işlevler, iç içe yerleştirilmiş sınıflar.
    • İstisna: Birbirini izleyen iki özellik arasında boş bir satır olması (aralarında başka kod olmaması) isteğe bağlıdır. Bu tür boş satırlar, mantıksal mülk grupları oluşturmak ve varsa özellikleri, destek mülkleriyle ilişkilendirmek için gerektiğinde kullanılır.
    • İstisna: Sıralama 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 ifadeler arasında, gerektiğinde.
  • İsteğe bağlı olarak bir işlevdeki 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 ( Yapı bölümü gibi) gerektirdiği şekilde.

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

Yatay

Dil veya diğer stil kurallarının gerektirdiği durumların ötesinde, hazır değerler, yorumlar ve KDoc 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 bir parantezden (() ayırmak.
    // WRONG!
    for(i in 0..1) {
    }
    
    // Okay
    for (i in 0..1) {
    }
    
  • else veya catch gibi ayrılmış bir kelimeyi, bu satırda kendisinden önce gelen bir kapanış parantezinden (}) ayırma.
    // WRONG!
    }else {
    }
    
    // Okay
    } else {
    }
    
  • Açık küme parantezinden ({) önce.
    // WRONG!
    if (list.isEmpty()){
    }
    
    // Okay
    if (list.isEmpty()) {
    }
    
  • İkili operatörde her iki taraf için de geçerlidir.
    // WRONG!
    val two = 1+1
    
    // Okay
    val two = 1 + 1
    
    Bu kural, 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() }
      
    Ancak şunlara izin verilmez:
    • üye referansının iki nokta üst üste işaretini (::).
      // WRONG!
      val toString = Any :: toString
      
      // Okay
      val toString = Any::toString
      
    • nokta ayırıcısı (.) kullanılır.
      // 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şaretinden (:) önce, 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 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 yorumu başlatan çift eğik çizginin (//) her iki tarafında. 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 gerektirecek veya buna izin verilmediği şeklinde yorumlanmaz; yalnızca iç mekanlara yöneliktir.

Belirli yapılar

Sıralama sınıfları

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

enum class Answer { YES, NO, MAYBE }

Bir numaralandırmadaki sabit değerler ayrı satırlara yerleştirildiğinde, bir gövde tanımladıkları durumlar dışında bunlar arasında boş bir satıra gerek yoktur.

enum class Answer {
    YES,
    NO,

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

Sıralama sınıfları sınıf olduğundan diğer tüm biçimlendirme sınıfları 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 belirli bir kullanım sitesi hedefiyle ve yalnızca 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

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

Bir ifade işlevinin gövdesi veya özellik başlatıcısı skaler bir değerse ya da döndürme türü, gövdeden açıkça anlaşılabilirse 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")

Bir kitaplık yazarken, genel API'nin parçası olduğunda açık tür bildirimini saklayın.

Adlandırma

Tanımlayıcılar yalnızca ASCII harfleri ile rakamları ve aşağıda belirtilen birkaç durumda 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 ön ekler veya sonekler, yedekleme özellikleri dışında kullanılmaz (Destek özellikleri bölümüne bakın).

Paket Adları

Paket adlarının tümü küçük harfle yazılır ve ardışık kelimeler birbirine bağlanır (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 isim kelime öbeklerinden oluşur. Örneğin, Character veya ImmutableList. Arayüz adları, isimler veya isim ifadeleri (ör. List) da 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ıyla başlar ve 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.

Alt çizgi işaretlerinin, adın mantıksal bileşenlerini ayırmak için test işlevi adlarında görünmesine izin verilir.

@Test fun pop_emptyStack() {
    // …
}

Ek açıklaması @Composable olan ve Unit değeri döndüren işlevler PascalCased'dır ve türler gibi isim olarak adlandırılır.

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

İşlev adları boşluk içermemelidir, çünkü Android'de bu özellik tam olarak desteklenmez.

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

Sabit adlar

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

Sabitler, özel bir get işlevi olmayan, içerikleri son derece sabit olan ve işlevlerinin algılanabilir yan etkileri olmayan val özellikleridir. Buna sabit türler ve sabit türlerin sabit koleksiyonlarının yanı sıra const olarak işaretlendiyse skaler ve dize dahildir. Bir örneğin gözlemlenebilir durumu değişebiliyorsa sabit değildir. Sadece nesneyi asla değiştirmeyi amaçlamak 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 bir bildirim olarak tanımlanabilir. Aksi takdirde sabit değer şartını karşılayan ancak class içinde tanımlanan değerler sabit olmayan bir ad kullanmalıdır.

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

Sabit olmayan adlar

Sabit olmayan adlar büyük/küçük harf kullanımıyla 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ı gerçek mülkün adıyla tam olarak eşleşmelidir (öne alt çizgi eklenmesi hariç).

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 bir 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 rakam gelir (ör. E, T, X, T2)
  • Sınıflar için kullanılan biçimde bir ad ve büyük T harfi (ör. RequestT, FooBarT)

Deve kılıfı

Bazen kısaltmalar veya “IPv6” ya da “iOS” gibi sıra dışı yapılar olması gibi İngilizce bir ifadeyi deve harfine dönüştürmenin birden fazla makul yolu vardır. Tahmin edilebilirliği iyileştirmek için aşağıdaki şemayı kullanın.

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

  1. İfadeyi düz ASCII'ye dönüştürün ve kesme işaretlerini kaldırın. Örneğin, “Müller algoritması” “Muellers algoritması” haline gelebilir.
  2. Bu sonucu kelimelere bölün, boşlukları ve kalan noktalama işaretlerini (genellikle kısa çizgileri) bölün. Önerilen: Herhangi bir kelime yaygın olarak bilinen geleneksel deve harf kullanımına sahipse bunu bileşenlerine ayırın (ör. “AdWords”, “reklam kelimeleri” haline gelir. “iOS” gibi bir kelimenin tek başına büyük/küçük harf kullanımı olmadığını, her kurala uygun olmadığını unutmayın. Dolayısıyla bu öneri geçerli değildir.
  3. Şimdi her şeyi (kısaltmalar dahil) küçük harfle yazdıktan sonra aşağıdakilerden birini yapın:
    • Paskal büyük/küçük harf kullanımı için her kelimenin ilk karakterini büyük harfle yazın.
    • Deve ilk harfini içeren 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ı neredeyse tamamen dikkate alınmaz.

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çe aktarma aracı" YouTubeImporter YoutubeImporter*

(* Kabul edilebilir, ancak önerilmez.)

Dokümanlar

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ığabildiğinde tek satırlı biçim değiştirilebilir. Bunun yalnızca @return gibi engelleme etiketi olmadığında geçerli olduğunu unutmayın.

Paragraf

Paragraflar arasında ve varsa blok etiketler grubundan önce boş bir satır (yani, başında hizalı yıldız işaretini (*) içeren bir satır) görünür.

Etiketleri engelle

Kullanılan standart "engelleme etiketleri"nden herhangi biri @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. Blok etiketi tek bir satıra sığmadığında devam satırları @ konumundan 4 boşluk girintili olarak gösterilir.

Özet parçası

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 metnin görünen tek bölümüdür.

Bu bir parçadır. Bir ad ifadesi veya fiil ifadesidir, tam bir cümle değildir. "A `Foo` is a..." veya "This method returns..." ile başlamaz ve "Save the record." gibi tam bir zorunluluk cümlesi oluşturması da gerekmez. Bununla birlikte, parça büyük harfle yazılmış ve tam bir cümleymiş gibi noktalama işaretleriyle gösterilmiştir.

Kullanım

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 KDoc mevcuttur.

İstisna: Kendini açıklayan işlevler

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

Tipik bir okuyucunun bilmesi gereken alakalı bilgilerin verilmemesi için bu istisnaya yer vermek uygun değildir. Örneğin, tipik bir okuyucunun "standart ad" teriminin ne anlama geldiğine dair hiçbir fikri yoksa getCanonicalName adlı işlev veya canonicalName adlı özellik ile ilgili dokümanlarını (mantıkıyla yalnızca /** Returns the canonical name. */ şeklinde olmalıdır) atlamayın.

İstisna: geçersiz kılmalar

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