Комментарии

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

В Kotlin есть три вида комментариев. Давайте взглянем на них.

Однострочные комментарии

Компилятор игнорирует любой текст от // до конца строки.

fun main() {
    // Строка ниже будет игнорироваться
    // println("Hello, World")

    // Выводит строку "Привет, Kotlin"
    println("Привет, Kotlin") // Тут может быть любой комментарий
}

?> Ты знал? В большинстве редакторов кода строку можно прокомментировать, поместив курсор на строку и нажав Ctrl+/ или ⌘+/

Многострочные комментарии

Компилятор игнорирует любой текст между символами /* и */. Вы можете использовать их для написания как однострочных, так и многострочных комментариев:

fun main() {
    /* Это однострочный комментарий */
    /* Это пример 
       многострочного комментария  */

    /* Все строки ниже будут игнорироваться
        println("Hello")
        println("World")
    */
}

Вы также можете помещать комментарии внутри других комментариев. При написании вложенных многострочных комментариев убедитесь, что открывающие /* и закрывающие */ образуют пары.

fun main() {
    /*
    println("Привет")  // печатает "Привет"
    println("Kotlin") /* Печатает "Kotlin" */
    */
}

Комментарии документации

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

Обычно эти комментарии помещаются над объявлениями соответствующих программных элементов. Кроме того, в этом случае для управления инструментом используются некоторые специальные метки, такие как @param, @return и другие.

Давайте взглянем на приведенный ниже пример.

/**
 * Функция `main` принимает строковые аргументы из командной строки.
 *
 * @param args аргументы из командной строки
 */
fun main(args: Array<String>) {
    // ничего не делаем
}

Не бойтесь, если вы еще не до конца понимаете комментарии к документации. Позже мы рассмотрим их поближе.

Заключение

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