Однострочные комментарии
Однострочные комментарии – это комментарии, которые пишутся между символами //. Они размещаются в отдельных строках и всё, что находится после этих символов комментирования – игнорируется компилятором. Например:
1 std::cout << «Hello, world!» << std::endl; // всё, что находится от начала двойного слеша - игнорируется компилятором
Как правило, однострочные комментарии используются для объяснения одной строчки кода:
1 std::cout << «Hello, world!» << std::endl; // cout и endl находятся в библиотеке iostream
2 std::cout << «It is so exciting!» << std::endl; // эти комментарии усложняют чтение кода
3 std::cout << «Yeah!» << std::endl; // особенно, когда строки разной длины
Размещая комментарии справа от кода, мы затрудняем себе как чтение кода, так и чтение комментариев. Следовательно, однострочные комментарии лучше размещать над строками кода:
1 // cout и endl находятся в библиотеке iostream
2 std::cout << «Hello, world!» << std::endl;
3
4 // теперь уже легче читать
5 std::cout << «It is so exciting!» << std::endl;
6
7 // не так ли?
8 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 // 1) Составляем список всех элементов.
4 // 2) Вычисляем среднее значение для каждого элемента, исходя из его веса, цвета и цены.
5 // 3) Выбираем любое число.
6 // 4) Определяем соответствие элемента случайно выбранному числу.
7 // 5) Возвращаем случайный элемент.
Эти комментарии позволяют пользователю понять, каким образом код выполняет поставленное ему задание.
В-третьих, на уровне стейтментов (однострочного кода) комментарии отвечают на вопрос «ПОЧЕМУ?»: «Почему код выполняет задание именно таким образом, а не другим?». Плохой комментарий на уровне стейтментов объясняет, что делает код. Если вы когда-нибудь писали код, который был настолько сложным, что нужен был комментарий, который бы объяснял, что он делает, то вам нужно было бы не писать комментарий, а переписывать целый код.
Примеры плохих и хороших однострочных комментариев:
Плохой комментарий:
1 // Присваиваем переменной sight значение 0
2 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 std::cout << 1;
2 std::cout << 2;
3 std::cout << 3;
Закомментировано символами однострочного комментария:
1 // std::cout << 1;
2 // std::cout << 2;
3 // std::cout << 3;
Закомментировано символами многострочного комментария:
1 /*
2 std::cout << 1;
3 std::cout << 2;
4 std::cout << 3;
5 */
Есть несколько причин, зачем использовать закомментирование:
Причина №1: Вы работаете над новой частью кода, которая пока что не рабочая, но вам нужно запустить программу. Компилятор не позволит выполнить программу, если в ней будут ошибки. Временное отделение нерабочего кода от рабочего комментированием позволит вам запустить программу. Когда код будет рабочий – сможете его легко раскомментировать и продолжить работу.
Причина №2: Вы написали код, который компилируется, но работает не так как нужно и сейчас у вас нет времени с этим разбираться. Закомментируйте код, а затем, когда будет время, исправьте в нём ошибки.
Причина №3: Поиск корня ошибки. Если программа производит не те результаты (или вообще происходит сбой), полезно будет поочерёдно «отключать» части вашего кода, чтобы понять какие из них рабочие, а какие создают проблемы. Если вы закомментируете одну или несколько строчек кода и программа начнёт корректно работать (или пропадут сбои), шансы того, что последнее, что вы закомментировали, является ошибкой – очень велики. После этого вы сможете разобраться с тем, почему же этот код не работает так, как нужно.
Причина №4: Тестирование нового кода. Вместо удаления старого кода, вы можете его закомментировать и оставить для справки, пока не будете уверены, что ваш новый код работает так, как нужно. Как только вы будете уверены в новом коде, то сможете без проблем удалить старые фрагменты кода. Если же новый код у вас будет работать не так, как нужно – вы сможете его удалить и выполнить откат к старому коду.
|