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

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

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 в именах файлов.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Используйте синтаксис именованных аргументов, когда метод принимает несколько параметров одного и того же примитивного типа или параметров типа 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 если имеется три или более вариантов.

Значения nullable Boolean в условиях

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

Циклы

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

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

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

Используйте функцию until для перебора открытого диапазона:

for (i in 0..n - 1) { /*...*/ }  // bad
for (i in 0 until 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, ограничьте видимость расширяющих функций настолько, насколько это целесообразно. По мере необходимости используйте локальные расширяющие функции, расширяющие функции-члены или расширяющие функции верхнего уровня с закрытой видимостью.

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

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

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

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

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

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 . Для получения руководства по выбору подходящей функции области для вашего случая, обратитесь к Функциям области.