4. Комментарии в коде

Комментарии в исходном коде это очень полезная вещь, если использовать их с умом.

Комментарии в коде нужны для человека. Компилятор их никак не обрабатывает и не записывает в код исполняемой программы.

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

Комментарии к строке чаще всего пишутся в конце строки // text

Комментарии для нескольких строк используются когда вам необходимо оставить больше информации.

/*
	text
	text
*/

С помощью комментариев можно скрыть от компилятора часть кода, чтобы проэксперементировать.

В следующем примере просто показаны примеры применения комментариев, но в реальной жизни так делать не нужно:

fn main() {
	print!("Первая строка");   // Это строка выведет текст и не перенесет строку
	print!("\n");              // Это символ \n позволяет сделать перенос строки
	/* Эти строки мы временно закомментируем
	println!("Вторая строка");
	println!("Третья строка");
	*/
	print!("Сумма 3 + 5 = {}", 3 + 5);  // Здесь мы выводим сумму 3 и 5
}

Как правильно использовать комментарии

Итак, уже на учебном примере мы видим, что множество комментариев захламляет код. Некоторые комментарии избыточны, например, код в строке 8 говорит сам за себя, его не нужно комментировать.

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

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

В этом курсе мы не будем их использовать, но запомните для общего кругозора.

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

Комментарии перед кодом ///

Комментарии в блоке кода //!

В таких комментариях может использоваться markdown разметка, которая позволит структурировать ваш текст и, при необходимости, экспортировать его в html. Подробнее в руководстве https://www.markdownguide.org/basic-syntax/

Пример:

/// # Учебный пример использования именованных аргументов
/// Здесь показано как использовать именованные аргументы
/// Дополнительный акцент на отсутствие необходимости соблюдения их последовательности
fn main() {
   println!("Студент {name} сдал экзамен на {grade}.", grade = 5, name = "Вася");
}