Комментарии в Rust

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

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

Самый частый комментарий начинается с //. Всё, что идёт после // в этой строке, игнорируется:

fn main() {
    // Это комментарий — Rust его полностью пропускает
    println!("Привет!"); // комментарий может стоять и в конце строки
}

Вывод:

Привет!

▶ Попробуй сам

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

Для длинной заметки можно начинать с // каждую строку:

fn main() {
    // Эта программа приветствует пользователя.
    // Она печатает одну строку текста.
    // Написана как первый пример.
    println!("Привет!");
}

Вывод:

Привет!

▶ Попробуй сам

Ещё Rust поддерживает блочные комментарии между /* и */, которые могут занимать несколько строк:

fn main() {
    /*
      Это блочный комментарий.
      Он может занимать несколько строк
      без // в начале каждой.
    */
    println!("Привет!");
}

Вывод:

Привет!

▶ Попробуй сам

На практике в большей части кода на Rust даже для нескольких строк используют // — так принято в сообществе, и это удобно с горячими клавишами редакторов.

Закомментировать код

Комментарии удобны, чтобы временно отключить строку, пока что-то проверяешь:

fn main() {
    println!("Это выполняется");
    // println!("Это пока отключено");
}

Вывод:

Это выполняется

▶ Попробуй сам

Совет

В большинстве редакторов можно выделить строки и нажать Ctrl + / (или Cmd + / на Mac), чтобы мгновенно закомментировать их или снять комментарий.

Комментарии, которые помогают

Комментарий, который повторяет код, ничего не добавляет. Код и так говорит, что происходит. Хороший комментарий объясняет почему или предупреждает о том, чего читатель не видит:

fn main() {
    let minutes = 135;

    // Таймер показывает только целые часы. Целочисленное деление
    // отбрасывает остаток — здесь нам нужно именно это.
    let hours = minutes / 60;
    let leftover = minutes - hours * 60; // минуты, которые не набрали целый час

    println!("{hours} ч {leftover} мин");
}

Вывод:

2 ч 15 мин

▶ Попробуй сам

Сравни это с комментарием вроде // делим минуты на 60. Он верный, но minutes / 60 и так может прочитать кто угодно. Полезная информация — почему деление здесь безопасно.

Ещё несколько привычек, которые стоит завести:

• Обновляй комментарии. Комментарий, который больше не совпадает с кодом, хуже, чем никакого: ему ведь верят.
• // TODO: — распространённый способ отметить незаконченную работу, например // TODO: обработать отрицательные числа. Многие редакторы подсвечивают такие пометки и умеют показать все TODO в проекте.
• В Rust блочные комментарии вкладываются друг в друга. В отличие от C, код, в котором уже есть комментарий /* */, можно обернуть ещё одним, и всё будет работать:

fn main() {
    /* Пока отключено:
       println!("старое приветствие"); /* здоровалось со всеми */
    */
    println!("новое приветствие");
}

Вывод:

новое приветствие

▶ Попробуй сам

Документирующие комментарии

В Rust есть особый вид комментариев, которые начинаются с /// (три косые черты). Это документирующие комментарии (doc comments): они описывают функции, и Rust умеет превращать их в сайт с документацией с помощью cargo doc.

/// Складывает два числа и возвращает результат.
fn add(a: i32, b: i32) -> i32 {
    a + b
}

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

Практика

1. Отключи одну строку

Эта программа печатает три строки. Преврати среднюю строку в комментарий, чтобы выводились только Строка 1 и Строка 3. Подсказка: поставь // в начало строки, которую хочешь отключить.

fn main() {
    println!("Строка 1");
    println!("Строка 2");
    println!("Строка 3");
}

Показать решение

fn main() {
    println!("Строка 1");
    // println!("Строка 2");
    println!("Строка 3");
}

Вывод:

Строка 1
Строка 3

▶ Попробуй сам

2. Отключи сразу две строки

Теперь выведи строки с Строка 1 по Строка 4, но отключи строки 2 и 3 одним блочным комментарием. Подсказка: начни комментарий с /* перед строкой 2 и закончи его */ после строки 3.

Показать решение

fn main() {
    println!("Строка 1");
    /*
    println!("Строка 2");
    println!("Строка 3");
    */
    println!("Строка 4");
}

Вывод:

Строка 1
Строка 4

▶ Попробуй сам

Итоги

• Комментарии — это заметки, которые Rust игнорирует; ими объясняют код.
• // начинает однострочный комментарий (самый частый вид).
• /* ... */ — блочный комментарий для нескольких строк, и такие комментарии можно вкладывать друг в друга.
• Хорошие комментарии объясняют почему, а не то, что код и так говорит.
• /// — документирующий комментарий, из него генерируется документация.

Проверь себя

Проверь себя

1. Что Rust делает с комментариями при компиляции кода?

Выполняет их как отладочный вывод Полностью игнорирует Превращает их в вызовы println!

2. Для чего нужны документирующие комментарии ///?

Чтобы отметить код, который потом удалят Чтобы генерировать документацию через cargo doc Чтобы временно отключить строку

Результат: 0 / 2

Что почитать

• Комментарии — книга «Язык программирования Rust»: короткий официальный раздел о комментариях // и о том, где их обычно ставят (перевод на русский).
• Комментарии — Rust на примерах: все стили комментариев в одном примере, включая блочные комментарии внутри выражения (перевод на русский).
• Публикация крейта на Crates.io — книга «Язык программирования Rust»: первое знакомство с /// и //! и с тем, как их использует cargo doc (перевод на русский).
• How to write documentation — The rustdoc book (на английском): советы о том, что должно быть в хорошем документирующем комментарии, — пригодится, когда будешь писать библиотеку.
• Comments — The Rust Reference (на английском): точные правила, включая вложенные блочные комментарии.