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

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

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

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

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

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

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

2. Откройте Kotlin | Проблемы стиля.

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

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

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

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

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

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

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

Размещение нескольких объявлений (классов, функций или свойств верхнего уровня) в одном файле 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 функции, содержащие глубоко неизменяемые данные), должны использовать имена с заглавными буквами через знак подчеркивания (стиль "screaming snake case"):

const val MAX_COUNT = 8
val USER_NAME_FIELD = "UserName"

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

val mutableCollection: MutableSet<String> = HashSet()

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

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

Для констант перечислений допустимо использовать имена с заглавными буквами через знак подчеркивания (стиль "screaming snake case") (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>

Если вы используете частный или внутренний псевдоним типа для предотвращения столкновения имён, предпочтительнее использовать 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 , если есть три или более вариантов.

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

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

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