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

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

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. Это относится ко всем типам классов и интерфейсов. Если файл содержит несколько классов или только объявления на верхнем уровне, выберите имя, описывающее содержимое файла, и назовите файл соответственно. Используйте верхний регистр с заглавной буквы (также известный как PascalCase), например, 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. Для получения руководства по выбору правильной функции области для вашего случая обратитесь к Функциям области.