Урок №9. Комментарии

Комментарий представляет собой текстовую строку или несколько строк, которые добавляются в исходный код с целью пояснения его функционала. В языке программирования C++ существует два вида комментариев: однострочные и многострочные.

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

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

std :: cout << «Hello , world ! » << std :: endl ; // всё, что находится справа от двойного слеша, - игнорируется компилятором

Обычно однострочные комментарии применяются для пояснения отдельной строки программного кода:

std :: cout << «Hello , world ! » << std :: endl ; // cout и endl находятся в библиотеке iostream

std :: cout << «It is so exciting ! » << std :: endl ; // эти комментарии усложняют чтение кода

std :: cout << «Yeah ! » << std :: endl ; // особенно, когда строки разной длины

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

// cout и endl находятся в библиотеке iostream

std :: cout << «Hello , world ! » << std :: endl ;

// теперь уже легче читать

std :: cout << «It is so exciting ! » << std :: endl ;

// не так ли?

std :: cout << «Yeah ! » << std :: endl ;

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

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

/* Это многострочный комментарий.

Эта строка игнорируется

и эта тоже. */

Иногда возникают ситуации, когда вы замечаете следующее, так как все, что находится между звездочками, игнорируется:

/* Это многострочный комментарий.

* Звёздочки слева

* упрощают чтение текста

*/

Невозможно вкладывать многострочные комментарии друг в друга (то есть один комментарий внутри другого):

/* Это многострочный /* комментарий */ а это уже не комментарий * /

// Верхний комментарий заканчивается перед первым */, а не перед вторым */

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

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

В начале, в контексте библиотек/программ/функций, комментарии помогают понять суть: «Что делают эти библиотеки/программы/функции?». Например:

// Эта программа вычисляет оценку студента за семестр на основе его оценок за модули

// Эта функция использует метод Ньютона для вычисления корня функции

// Следующий код генерирует случайное число

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

Во-вторых, внутри библиотек/программ/функций комментарии помогают понять, как именно выполняется код: «Какая логика реализована в данном участке программы?». Например:

/* Для расчета итоговой оценки ученика, мы складываем все его оценки за уроки и домашние задания,

а затем делим получившееся число на общее количество оценок.

Таким образом, мы получаем средний балл ученика. */

Или же:

// Чтобы получить рандомный (случайный) элемент, мы выполняем следующее:

// 1) Составляем список всех элементов.

// 2) Вычисляем среднее значение для каждого элемента, исходя из его веса, цвета и цены.

// 3) Выбираем любое число.

// 4) Определяем соответствие элемента случайно выбранному числу.

// 5) Возвращаем случайный элемент.

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

В-третьих, на уровне отдельных строк кода комментарии отвечают на вопрос «ПОЧЕМУ?» : «Почему код работает именно так, а не иначе?». Плохой комментарий на уровне стейтментов просто повторяет функционал кода. Если вам приходилось добавлять комментарии к сложному коду, чтобы объяснить его работу, возможно, стоит пересмотреть этот код.

Примеры качественных и некачественных однострочных замечаний:

Негативный отзыв:

// Присваиваем переменной sight значение 0

sight = 0 ;

(Это понятно и без объяснений)

Отличный отзыв:

// Игрок выпил зелье слепоты и ничего не видит

sight = 0 ;

(Теперь мы понимаем, ПРИЧИНУ того, что у игрока отсутствует зрение)

Негативный отзыв:

// Рассчитываем стоимость элементов

cost = items / 2 * storePrice ;

(Да, мы понимаем, что здесь происходит расчет стоимости, но почему элементы разделены на две части?)

Отличный отзыв:

// Нам нужно разделить все элементы на 2, потому что они куплены по парам

cost = items / 2 * storePrice ;

(Теперь все стало ясно!)

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

Положительные отзывы:

// Мы решили использовать список вместо массива,

// потому что массивы осуществляют медленную вставку.

Или таким образом:

// Мы используем метод Ньютона для вычисления корня функции,

// так как другого детерминистического способа решения этой задачи - нет.

Необходимо писать комментарии так, чтобы даже человек без опыта в программировании мог понять ваш код. Часто бывает, что программист уверен: "Все понятно, что делает код! Я не забуду!". Но через некоторое время он уже не помнит. Поэтому важно оставлять комментарии, объясняющие на простом языке, что и зачем делает ваш код. Это поможет не только вам, но и другим разработчикам. Читать код легко, понимать его логику и смысл - сложнее.

Подведем итог:

При работе с библиотеками, программами и функциями важно делать заметки, отвечая на вопрос "ЧТО?".

При работе с библиотеками, программами и функциями важно не забывать добавлять комментарии, которые отвечают на вопрос «КАК?».

При написании высказываний важно добавлять пояснения, объясняя причину с помощью комментариев.

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

Преобразование кода в комментарии - это процесс превращения одной или нескольких строк кода в комментарии. Это позволяет временно исключить определенную часть кода из процесса компиляции.

Для того чтобы прокомментировать одну строку кода, необходимо использовать однострочные символы "//".

Не было оставлено комментариев:

std :: cout << 1 ;

Прокомментировано:

//    std::cout << 1;

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

Не прокомментировано:

std :: cout << 1 ;

std :: cout << 2 ;

std :: cout << 3 ;

Однострочный комментарий закомментирован символами:

//    std::cout << 1;

//    std::cout << 2;

//    std::cout << 3;

Многострочный комментарий закомментирован при помощи специальных символов:

/*

std::cout << 1;

std::cout << 2;

std::cout << 3;

*/

Существует несколько аргументов в пользу использования "комментирования":

Одной из причин, по которой вам может понадобиться временно закомментировать часть кода, является работа над новым участком программы, который пока не функционирует должным образом, но требуется запустить программу. Компилятор не даст возможности выполнить программу в случае наличия ошибок. Отделение нерабочего кода от рабочего путем комментирования позволит вам запустить программу. После того, как код станет рабочим, вы сможете легко раскомментировать его и продолжить работу.

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

Третья причина: Поиск корня проблемы. Если вы не удовлетворены результатами работы программы (или она вообще выходит из строя), полезно будет поочередно "отключать" части вашего кода, чтобы определить, какие из них работают, а какие вызывают проблемы. Если вы закомментируете одну или несколько строк кода и программа начнет работать правильно (или проблемы исчезнут), вероятность того, что последнее, что вы закомментировали, является ошибкой, очень высока. После этого вы сможете разобраться в том, почему этот код не работает так, как задумано.

Причина №4: Проверка нового кода. Вместо того чтобы удалять старый код, вы можете закомментировать его и оставить для справки до тех пор, пока не будете уверены, что ваш новый код работает правильно. Как только вы убедитесь в новом коде, вы сможете легко удалить старые фрагменты кода. Если же новый код не будет работать правильно, вы сможете его удалить и вернуться к старому коду.

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