Урок 9. Комментарии в C++

   | 

   | 

 Обновлено 2 Янв 2018  | 

 14923

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

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

Однострочные комментарии (single-line comments) используют символы //. Их пишут в каждой строке отдельно и всё, что идет после этих символов — игнорируется компилятором. Например:

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

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

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

Многострочные комментарии  (multi-line comments) используют символы /* */. Всё, что находится между звёздочками — игнорируется.

Так как всё, что находится между звёздочками — игнорируется, то иногда вы сможете увидеть, как программисты «украшают» свои многострочные комментарии:

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

Правило: Никогда не размещайте одни комментарии внутри других.

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

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

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

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

Эти комментарии дают пользователю понять, каким образом код работает для выполнения задания, при этом не вдаваясь особо в подробности.

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

Вот примеры плохих и хороших однострочных комментариев:

плохой комментарий:

(да мы уже и так видим по коду, что sight равно нулю)



хороший комментарий:

(Теперь мы знаем, ПОЧЕМУ зрение у игрока равно нулю)

плохой комментарий:

(Так, мы видим, что это расчет стоимости, но почему элементы делятся на 2?)

хороший комментарий:

(теперь мы поняли!)

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

хорошие комментарии:

И, наконец, комментарии нужно писать так, чтобы человек, который не имеет ни малейшего представления о том, что должен делать код – смог в нем разобраться. Очень часто бывают ситуации, когда программист может сказать: «Это же совершенно очевидно, что это делает! Я это точно не забуду». Угадайте, что? Это не совершенно очевидно и вы удивитесь, как скоро вы это забудете. Вы (или кто-то другой) будете очень благодарны себе за то, что оставите комментарии объясняя на человеческом языке что, как и почему делает ваш код. Читать отдельные строки кода легко. Понимать их логику и смысл – нет.

Итого:

  На уровне целых библиотек, программ или функций комментируйте, отвечая на вопрос «ЧТО?»;

  Внутри библиотек, программ или функций комментируйте, отвечая на вопрос «КАК?»;

  На уровне инструкций комментируйте, отвечая на вопрос «ПОЧЕМУ?».

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

Закомментировать код – это значит конвертировать одну или нескольких строк кода в комментарий. Таким образом, вы сможете (временно) исключить части кода от компиляции.

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

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

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

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

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

Закомментировано однострочным:

Многострочным:

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

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

2) Вы написали код, который компилируется, но работает не так как надо и у вас сейчас нет времени это исправлять. Закомментируйте код, не допустив его к компиляции и не создав дополнительных проблем. Код останется нейтральным, пока вы его не пофиксите.

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

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

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

Оценить статью:

Звёзд: 1Звёзд: 2Звёзд: 3Звёзд: 4Звёзд: 5 (197 оценок, среднее: 4,95 из 5)
Загрузка...
Подписаться на обновления:

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *

ПОДПИСЫВАЙТЕСЬ

НА КАНАЛ RAVESLI В TELEGRAM

@ravesli

ПОДПИСАТЬСЯ БЕСПЛАТНО