Рекомендации по стилю кодирования

Применение руководства по стилю

1. Перейдите в Настройки/Предпочтения | Редактор | Стиль кода | Kotlin.

2. Нажмите Установить из....

3. Выберите Руководство по стилю Kotlin.

Проверка соответствия кода руководству по стилю

1. Перейдите в Настройки/Предпочтения | Редактор | Проверки | Общие.

2. Включите проверку Неправильное форматирование. Дополнительные проверки, которые проверяют другие аспекты, описанные в руководстве по стилю (например, соглашения об именовании), включены по умолчанию.

Структура каталогов

В чистых проектах Kotlin рекомендуемая структура каталогов соответствует структуре пакетов без общего корневого пакета. Например, если весь код проекта находится в пакете org.example.kotlin и его подпакетах, файлы с пакетом org.example.kotlin должны располагаться непосредственно в корне источника, а файлы в org.example.kotlin.network.socket — в подкаталоге network/socket корня источника.

Имена файлов исходного кода

Если файл Kotlin содержит единственный класс или интерфейс (возможно, с сопутствующими объявлениями на верхнем уровне), его имя должно совпадать с именем класса с добавлением расширения .kt. Это относится ко всем видам классов и интерфейсов. Если файл содержит несколько классов или только объявления на верхнем уровне, выберите имя, описывающее содержимое файла, и дайте ему соответствующее имя. Используйте верхний регистр с большой буквы (также известный как паскаль-кейс), например, ProcessDeclarations.kt.

Имя файла должно описывать, что делает код в файле. Поэтому следует избегать бессмысленных слов, таких как Util в именах файлов.

root
|- commonMain/kotlin/myPackage/Platform.kt // contains 'fun count() { }'
|- jvmMain/kotlin/myPackage/Platform.kt // contains 'fun multiply() { }'

Организация файлов исходного кода

Размещение нескольких объявлений (классов, функций или свойств на верхнем уровне) в одном файле Kotlin поощряется, если эти объявления тесно связаны между собой по смыслу, и размер файла остается разумным (не превышает несколько сотен строк).

В частности, при определении расширяющих функций для класса, которые актуальны для всех клиентов этого класса, поместите их в тот же файл, что и сам класс. При определении расширяющих функций, которые имеют смысл только для конкретного клиента, поместите их рядом с кодом этого клиента. Избегайте создания файлов только для хранения всех расширяющих функций для какого-либо класса.

Структура класса

Содержание класса должно идти в следующем порядке:

1. Объявления свойств и инициализирующие блоки

2. Вторичные конструкторы

3. Объявления методов

4. Объект-компаньон

Не сортируйте объявления методов в алфавитном порядке или по видимост, и не разделяйте обычные методы и расширяющие методы. Вместо этого группируйте связанные элементы, чтобы человек, читающий класс сверху вниз, мог следить за логикой происходящего. Выберите порядок (сначала более высокие уровни или наоборот) и придерживайтесь его.

Поместите вложенные классы рядом с кодом, использующим эти классы. Если классы предназначены для внешнего использования и не ссылаются внутри класса, поместите их в конце, после объекта-компаньона.

Структура реализации интерфейса

При реализации интерфейса сохраняйте реализующие члены в том же порядке, что и члены интерфейса (при необходимости, чередуя их с дополнительными закрытыми методами, используемыми для реализации).

Структура перегрузки

Всегда помещайте перегрузки рядом друг с другом в классе.

Имена функций

Имена функций, свойств и локальных переменных начинаются со строчной буквы, используют верблюжье написание и не содержат нижних подчеркиваний:

fun processDeclarations() { /*...*/ }
var declarationCount = 1

Исключение: функции-фабрики, используемые для создания экземпляров классов, могут иметь такое же имя, как абстрактный возвращаемый тип:

interface Foo { /*...*/ }

class FooImpl : Foo { /*...*/ }

fun Foo(): Foo { return FooImpl() }

Имена методов тестов

В тестах (и только в тестах) вы можете использовать имена методов с пробелами, заключенными в обратные кавычки. Обратите внимание, что такие имена методов в настоящее время не поддерживаются средой выполнения Android. Нижние подчеркивания в именах методов также разрешены в тестовом коде.

class MyTestCase {
     @Test fun `ensure everything works`() { /*...*/ }
     
     @Test fun ensureEverythingWorks_onAndroid() { /*...*/ }
}

Имена свойств

Имена констант (свойства, помеченные const, или свойства верхнего уровня или объекта val без пользовательской get функции, которые хранят глубоко неизменяемые данные) должны использовать имена с заглавными буквами, разделённые нижними подчеркиваниями (назывной стиль):

const val MAX_COUNT = 8
val USER_NAME_FIELD = "UserName"

Имена свойств верхнего уровня или объекта, которые хранят объекты с поведением или изменяемыми данными, должны использовать имена с верблюжьим написанием:

val mutableCollection: MutableSet<String> = HashSet()

Имена свойств, хранящих ссылки на одиночные объекты, могут использовать тот же стиль именования, что и object объявления:

val PersonComparator: Comparator<Person> = /*...*/

Для констант перечислений допустимо использовать либо имена с заглавными буквами, разделённые нижними подчеркиваниями (назывной стиль) (enum class Color { RED, GREEN }) или имена с заглавными буквами верблюжьего написания, в зависимости от использования.

Имена вспомогательных свойств

Если у класса есть два свойства, которые концептуально одинаковы, но одно является частью публичного API, а другое — деталью реализации, используйте нижнее подчеркивание в качестве префикса для имени частного свойства:

class C {
    private val _elementList = mutableListOf<Element>()

    val elementList: List<Element>
         get() = _elementList
}

Выбор хороших имён

Имя класса обычно представляет собой существительное или существительное с уточнением, описывающее, что делает класс: List, PersonReader.

Имя метода обычно является глаголом или глаголом с уточнением, описывающим, что делает метод: close, readPersons. Имя также должно указывать, изменяет ли метод объект или возвращает новый. Например, sort сортирует коллекцию на месте, в то время как sorted возвращает отсортированную копию коллекции.

Имена должны ясно указывать назначение сущности, поэтому лучше избегать использования бессмысленных слов (Manager, Wrapper) в именах.

При использовании аббревиатуры в имени объявления, запишите её заглавными буквами, если она состоит из двух букв (IOStream); запишите только первую букву заглавной, если она длиннее (XmlFormatter, HttpInputStream).

Тип возвращаемого значения Unit

Если функция возвращает Unit, тип возвращаемого значения следует опустить:

fun foo() { // ": Unit" is omitted here

}

Точки с запятой

Опускайте точки с запятой, когда это возможно.

Шаблоны строк

Не используйте фигурные скобки при вставке простой переменной в шаблон строки. Используйте фигурные скобки только для более сложных выражений.

println("$name has ${children.size} children")

Неизменяемость

Предпочтительно использовать неизменяемые данные вместо изменяемых. Всегда объявляйте локальные переменные и свойства как val вместо var, если они не изменяются после инициализации.

Всегда используйте неизменяемые интерфейсы коллекций (Collection, List, Set, Map) для объявления коллекций, которые не мутируются. При использовании функций-фабрик для создания экземпляров коллекций всегда используйте функции, возвращающие неизменяемые типы коллекций, когда это возможно:

// Bad: use of a mutable collection type for value which will not be mutated
fun validateValue(actualValue: String, allowedValues: HashSet<String>) { ... }

// Good: immutable collection type used instead
fun validateValue(actualValue: String, allowedValues: Set<String>) { ... }

// Bad: arrayListOf() returns ArrayList<T>, which is a mutable collection type
val allowedValues = arrayListOf("a", "b", "c")

// Good: listOf() returns List<T>
val allowedValues = listOf("a", "b", "c")

Значения параметров по умолчанию

Предпочтительнее объявлять функции со значениями параметров по умолчанию, чем объявлять перегруженные функции.

// Bad
fun foo() = foo("a")
fun foo(a: String) { /*...*/ }

// Good
fun foo(a: String = "a") { /*...*/ }

Псевдонимы типов

Если у вас есть функциональный тип или тип с параметрами типа, который используется несколько раз в кодовой базе, предпочтительнее определить для него псевдоним типа:

typealias MouseClickHandler = (Any, MouseEvent) -> Unit
typealias PersonIndex = Map<String, Person>

Если вы используете частный или внутренний псевдоним типа для предотвращения коллизий имён, предпочтительнее использовать import ... as ..., упомянутый в Разделах и импортах.

Параметры лямбда-выражений

В лямбда-выражениях, которые короткие и не вложенные, рекомендуется использовать it соглашение вместо явного объявления параметров. Во вложенных лямбда-выражениях с параметрами всегда объявляйте параметры явно.

Возврат в лямбда-выражении

Избегайте использования нескольких меток возврата в лямбда-выражении. Подумайте о реструктуризации лямбда-выражения таким образом, чтобы у него был единственный выходной пункт. Если это невозможно или не достаточно ясно, рассмотрите возможность преобразования лямбда-выражения в анонимную функцию.

Не используйте метку возврата для последнего оператора в лямбда-выражении.

Именованные аргументы

Используйте синтаксис именованных аргументов, когда метод принимает несколько параметров одного и того же примитивного типа или для параметров типа Boolean, если смысл всех параметров не абсолютно ясен из контекста.

drawSquare(x = 10, y = 10, width = 100, height = 100, fill = true)

Условные операторы

Предпочтительно использовать выразительную форму try, if, и when.

return if (x) foo() else bar()

return when(x) {
    0 -> "zero"
    else -> "nonzero"
}

Предпочтительнее, чем:

if (x)
    return foo()
else
    return bar()

when(x) {
    0 -> return "zero"
    else -> return "nonzero"
}    

if или when

Предпочтительно использовать if для бинарных условий вместо when. Например, используйте этот синтаксис с if:

if (x == null) ... else ...

вместо этого с when:

when (x) {
    null -> // ...
    else -> // ...
}

Предпочтительно использовать when если есть три или более вариантов.

Значения типа Boolean с возможностью null в условиях

Если вам нужно использовать значение типа Boolean с возможностью null в условном операторе, используйте проверки if (value == true) или if (value == false).

Циклы

Предпочтительно использовать функции высшего порядка (filter, map и т.д.) вместо циклов. Исключение: forEach (предпочтительно использовать обычный for цикл вместо, если получатель forEach имеет возможность null или forEach используется как часть более длинной цепочки вызовов).

При выборе между сложным выражением с использованием нескольких функций высшего порядка и циклом, учитывайте стоимость выполняемых операций в каждом случае и учитывайте соображения производительности.

Циклы по диапазонам

Используйте оператор ..< для цикла по открытому диапазону:

for (i in 0..n - 1) { /*...*/ }  // bad
for (i in 0..<n) { /*...*/ }  // good

Строки

Предпочтительнее использовать шаблоны строк вместо конкатенации строк.

Предпочтительнее использовать многострочные строки вместо встраивания \n последовательностей экранирования в обычные строковые литералы.

Для сохранения отступов в многострочных строках используйте trimIndent, когда результирующая строка не требует внутренних отступов, или trimMargin, когда требуются внутренние отступы:

fun main() {
//sampleStart
   println("""
    Not
    trimmed
    text
    """
   )

   println("""
    Trimmed
    text
    """.trimIndent()
   )

   println()

   val a = """Trimmed to margin text:
          |if(a > 1) {
          |    return a
          |}""".trimMargin()

   println(a)
//sampleEnd
}

Узнайте разницу между Java и Kotlin многострочными строками.

Функции и свойства

В некоторых случаях функции без аргументов могут быть взаимозаменяемы с только для чтения свойствами. Несмотря на схожую семантику, есть некоторые стилистические соглашения о том, когда предпочесть одно другому.

Предпочитайте свойство функции, когда алгоритм:

• не бросает исключения

• дешево вычисляется (или кэшируется при первом выполнении)

• возвращает тот же результат при вызовах, если состояние объекта не изменилось

Расширяющие функции

Либерально используйте расширяющие функции. Каждый раз, когда у вас есть функция, которая в основном работает с объектом, подумайте о том, чтобы сделать её расширяющей функцией, принимающей этот объект в качестве получателя. Для минимизации загрязнения API, ограничивайте видимость расширяющих функций так, как это имеет смысл. По мере необходимости используйте локальные расширяющие функции, расширяющие функции-члены или расширяющие функции верхнего уровня с закрытой видимостью.

Инфиксные функции

Объявляйте функцию как infix только тогда, когда она работает с двумя объектами, играющими аналогичную роль. Хорошие примеры: and, to, zip. Плохой пример: add.

Не объявляйте метод как infix если он изменяет объект-получатель.

Функции-фабрики

Если вы объявляете функцию-фабрику для класса, избегайте присвоения ей того же имени, что и классу. Предпочитайте использовать отличное имя, делая ясным, почему поведение функции-фабрики является специальным. Только если нет специальной семантики, вы можете использовать то же имя, что и класс.

class Point(val x: Double, val y: Double) {
    companion object {
        fun fromPolar(angle: Double, radius: Double) = Point(...)
    }
}

Если у вас есть объект с несколькими перегруженными конструкторами, которые не вызывают разные конструкторы суперкласса и не могут быть сведены к одному конструктору со значениями параметров по умолчанию, предпочтительнее заменить перегруженные конструкторы функциями-фабриками.

Типы платформы

Функция/метод публичного уровня, возвращающий выражение типа платформы, должен явно указать свой тип Kotlin:

fun apiCall(): String = MyJavaApi.getProperty("name")

Любое свойство (на уровне пакета или класса), инициализированное выражением типа платформы, должно явно указывать свой тип Kotlin:

class Person {
    val name: String = MyJavaApi.getProperty("name")
}

Локальная переменная, инициализированная выражением типа платформы, может или не может иметь объявление типа:

fun main() {
    val name = MyJavaApi.getProperty("name")
    println(name)
}

Функции области apply/with/run/also/let

Kotlin предоставляет набор функций для выполнения блока кода в контексте заданного объекта: let, run, with, apply, и also. Для получения руководства по выбору подходящей функции области для вашего случая, обратитесь к Функциям области.