Комментарий — это строка (или несколько строк) текста, которая вставляется в исходный код для объяснения того, что делает код. В языке C++ есть 2 типа комментариев: однострочные и многострочные.
Однострочные комментарии
Однострочные комментарии — это комментарии, которые пишутся после символов //
. Они пишутся в отдельных строках и всё, что находится после этих символов комментирования, — игнорируется компилятором, например:
1 |
std::cout << «Hello, world!» << std::endl; // всё, что находится справа от двойного слеша, - игнорируется компилятором |
Как правило, однострочные комментарии используются для объяснения одной строчки кода:
1 2 3 |
std::cout << «Hello, world!» << std::endl; // cout и endl находятся в библиотеке iostream std::cout << «It is so exciting!» << std::endl; // эти комментарии усложняют чтение кода std::cout << «Yeah!» << std::endl; // особенно, когда строки разной длины |
Размещая комментарии справа от кода, мы затрудняем себе как чтение кода, так и чтение комментариев. Следовательно, однострочные комментарии лучше размещать над строками кода:
1 2 3 4 5 6 7 8 |
// 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 |
/* Это многострочный комментарий. Эта строка игнорируется и эта тоже. */ |
Так как всё, что находится между звёздочками, — игнорируется, то иногда вы можете наблюдать следующее:
1 2 3 4 |
/* Это многострочный комментарий. * Звёздочки слева * упрощают чтение текста */ |
Многострочные комментарии не могут быть вложенными (т.е. одни комментарии внутри других):
1 2 |
/* Это многострочный /* комментарий */ а это уже не комментарий */ // Верхний комментарий заканчивается перед первым */, а не перед вторым */ |
Правило: Никогда не используйте вложенные комментарии.
Как правильно писать комментарии?
Во-первых, на уровне библиотек/программ/функций комментарии отвечают на вопрос «ЧТО?»: «Что делают эти библиотеки/программы/функции?». Например:
1 2 3 4 5 |
// Эта программа вычисляет оценку студента за семестр на основе его оценок за модули // Эта функция использует метод Ньютона для вычисления корня функции // Следующий код генерирует случайное число |
Все эти комментарии позволяют понять, что делает программа, без необходимости смотреть на исходный код. Это особенно важно специалистам, работающим в команде, где не каждый специалист будет знаком со всем имеющимся кодом.
Во-вторых, внутри библиотек/программ/функций комментарии отвечают на вопрос «КАК?»: «Как код выполняет задание?». Например:
1 2 3 |
/* Для расчета итоговой оценки ученика, мы складываем все его оценки за уроки и домашние задания, а затем делим получившееся число на общее количество оценок. Таким образом, мы получаем средний балл ученика. */ |
Или:
1 2 3 4 5 6 7 |
// Чтобы получить рандомный (случайный) элемент, мы выполняем следующее: // 1) Составляем список всех элементов. // 2) Вычисляем среднее значение для каждого элемента, исходя из его веса, цвета и цены. // 3) Выбираем любое число. // 4) Определяем соответствие элемента случайно выбранному числу. // 5) Возвращаем случайный элемент. |
Эти комментарии позволяют читателю понять, каким образом код выполняет поставленное ему задание.
В-третьих, на уровне стейтментов (однострочного кода) комментарии отвечают на вопрос «ПОЧЕМУ?»: «Почему код выполняет задание именно так, а не иначе?». Плохой комментарий на уровне стейтментов объясняет, что делает код. Если вы когда-нибудь писали код, который был настолько сложным, что нужен был комментарий, который бы объяснял, что он делает, то вам нужно было бы не писать комментарий, а переписывать этот код.
Примеры плохих и хороших однострочных комментариев:
Плохой комментарий:
1 2 |
// Присваиваем переменной sight значение 0 sight = 0; |
(По коду это и так понятно)
Хороший комментарий:
1 2 |
// Игрок выпил зелье слепоты и ничего не видит sight = 0; |
(Теперь мы знаем, ПОЧЕМУ зрение у игрока равно нулю)
Плохой комментарий:
1 2 |
// Рассчитываем стоимость элементов cost = items / 2 * storePrice; |
(Да, мы видим, что здесь подсчет стоимости, но почему элементы делятся на 2?)
Хороший комментарий:
1 2 |
// Нам нужно разделить все элементы на 2, потому что они куплены по парам cost = items / 2 * storePrice; |
(Теперь понятно!)
Программистам часто приходится принимать трудные решения по поводу того, каким способом решить проблему. А комментарии и существуют для того, чтобы напомнить себе (или объяснить другим) причину, почему вы написали код именно так, а не иначе.
Хорошие комментарии:
1 2 |
// Мы решили использовать список вместо массива, // потому что массивы осуществляют медленную вставку. |
Или:
1 2 |
// Мы используем метод Ньютона для вычисления корня функции, // так как другого детерминистического способа решения этой задачи - нет. |
И, наконец, комментарии нужно писать так, чтобы человек, который не имеет ни малейшего представления о том, что делает ваш код — смог в нем разобраться. Очень часто случаются ситуации, когда программист говорит: «Это же совершенно очевидно, что делает код! Я это точно не забуду!». Угадайте, что случится через несколько недель или даже дней? Это не совершенно очевидно, и вы удивитесь, как скоро вы забудете то, что делает ваш код. Вы (или кто-то другой) будете очень благодарны себе за то, что оставите комментарии, объясняя на человеческом языке что, как и почему делает ваш код. Читать отдельные строки кода — легко, понимать их логику и смысл — сложно.
Подытожим:
На уровне библиотек/программ/функций оставляйте комментарии, отвечая на вопрос «ЧТО?».
Внутри библиотек/программ/функций оставляйте комментарии, отвечая на вопрос «КАК?».
На уровне стейтментов оставляйте комментарии, отвечая на вопрос «ПОЧЕМУ?».
Закомментировать код
Закомментировать код — это конвертировать одну или несколько строк кода в комментарии. Таким образом, вы можете (временно) исключить часть кода из компиляции.
Чтобы закомментировать одну строку кода, используйте однострочные символы комментирования //
.
Не закомментировано:
1 |
std::cout << 1; |
Закомментировано:
1 |
// std::cout << 1; |
Чтобы закомментировать блок кода, используйте однострочные символы комментирования //
на каждой строке или символы многострочного комментария /* */
.
Не закомментировано:
1 2 3 |
std::cout << 1; std::cout << 2; std::cout << 3; |
Закомментировано символами однострочного комментария:
1 2 3 |
// std::cout << 1; // std::cout << 2; // std::cout << 3; |
Закомментировано символами многострочного комментария:
1 2 3 4 5 |
/* std::cout << 1; std::cout << 2; std::cout << 3; */ |
Есть несколько причин, почему следует использовать «закомментирование»:
Причина №1: Вы работаете над новой частью кода, которая пока что не рабочая, но вам нужно запустить программу. Компилятор не позволит выполнить программу, если в ней будут ошибки. Временное отделение нерабочего кода от рабочего комментированием позволит вам запустить программу. Когда код будет рабочий, то вы сможете его легко раскомментировать и продолжить работу.
Причина №2: Вы написали код, который компилируется, но работает не так, как нужно и сейчас у вас нет времени с этим возиться. Закомментируйте код, а затем, когда будет время, исправьте ошибки.
Причина №3: Поиск корня ошибки. Если вас не устраивают результаты работы программы (или вообще происходит сбой), полезно будет поочерёдно «отключать» части вашего кода, чтобы понять какие из них рабочие, а какие — создают проблемы. Если вы закомментируете одну или несколько строчек кода и программа начнет корректно работать (или пропадут сбои), шансы того, что последнее, что вы закомментировали, является ошибкой — очень велики. После этого вы сможете разобраться с тем, почему же этот код не работает так, как нужно.
Причина №4: Тестирование нового кода. Вместо удаления старого кода, вы можете его закомментировать и оставить для справки, пока не будете уверены в том, что ваш новый код работает так, как нужно. Как только вы будете уверены в новом коде, то сможете без проблем удалить старые фрагменты кода. Если же новый код у вас будет работать не так, как нужно, то вы сможете его удалить и откатиться к старому коду.
Примечание: Во всех следующих уроках я буду использовать комментарии в иллюстративных целях. Внимательные читатели смогут заметить, что по вышеуказанным стандартам большинство из этих комментариев будут плохими. Но помните, что использовать я их буду в образовательных целях, а не для демонстрации хороших примеров.
Очень понятно все. Думаю для базы этого достаточно, создал базу — идешь в учебники. В учебниках для новичков ничего не понятно, а тут все понятно. Спасибо за понятное объяснение материала!
Пожалуйста)
Сколько смотрела разных видео, читала сайты, ни у кого так доступно не была эта тема раскрыта. Спасибо автору за проделанную работу, практические советы очень полезны.
Пожалуйста)) Очень круто, что Равесли оказался Вам полезным))
Огромная благодарность за Ваш труд. Мне скоро 50, программировал станки с ЧПУ (В Германии) и многим другими направлениями занимался и занимаюсь, еще в школе говорили, в программировании будущее. Ну вот, до меня наконец-то дошло, что пора обратить внимание на знаки судьбы.
Пожалуйста)
Спасибо вам, Юрий! В ваших статьях очень много полезной информации. Я изучаю C++ уже 5 месяцев, и ваши статьи помогают заполнить пробелы в теоретической части языка
И за эти статьи тоже спасибо огромное! Очень помогает подготовиться к экзу по АиП и заполнить пробелы 😉
Пожалуйста) Рад, что Равесли оказался для вас полезным)
А можете написать уроки по языку программирование Haskell или Erlang Ocaml
Если бы это было так просто, как написать комментарий — то уже были бы уроки к 20 языкам программирования)
Спасибо Вам за этот прекрасный и доступный курс. Я сам преподаватель информатики и этот курс читаю с огромным удовольствием!!! Спасибо Вам за Ваш громадный и прекрасный курс!!!
Пожалуйста 🙂
А если необходимо символы /* */ запихнуть в строковую переменную, то как это сделать правильно, не сломая его?
Используйте символ обратного слэша — \
Например:
Зачем заключать нерабочий код в комментарий?
Помойму легче скопировать его и куда нибудь сохранить.. Потом достать вставить и доделать
1)чтоб был под носом (никуда его не переносить)
2)удобство — гораздо проще кликнуть пару слешей или обозначать область /* */ . Чем держать в дампе или переносить куда-либо.
Мне 50, я одинок, имею кучу времени, некую давнюю мечту — что то сделать самому… — И вот: С++ мне в помощь!!
Очень благодарен Автору! Вы даёте импульс жить дальше!.
Приятно, что оказался вам полезен 🙂
Ты забыл о третьем виде коментариев — тройной слеш.
Новое понимание комментария. Спасибо! Это другой взгляд или взгляд с другой стороны.
В третьей части урока мы создаём второй уровень для игры Кот в лабиринте и закрепляем команды Scratch для реализации движения спрайтов по координатам.
Самая легкая тема в программирований)))
Написание хороших комментариев — одна из наиболее сложных задач в программировании, а отнюдь не самая лёгкая. Спасибо автору за грамотное изложение того, что именно надо писать в комментариях, и за наглядные примеры.
А почему "ravesli" ?
Просто так. Название ни к чему не привязано.
Я то думаю что так сложно запомнить название , проще курс запомнить
Спасибо, узнал, что можно "закомментировать"