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

   ⁄ 

 Обновлено 24 Фев 2017

  ⁄   

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Небольшая заметка о комментариях в туториале

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

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

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

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

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