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

  Юрий  | 

  |

  Обновл. 21 Май 2023  | 

 192965

 ǀ   28 

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

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

Однострочные комментарии — это комментарии, которые пишутся после символов //. Они пишутся в отдельных строках и всё, что находится после этих символов комментирования, — игнорируется компилятором, например:

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

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

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


Многострочные комментарии — это комментарии, которые пишутся между символами /* */. Всё, что находится между звёздочками, — игнорируется компилятором:

Так как всё, что находится между звёздочками, — игнорируется, то иногда вы можете наблюдать следующее:

Многострочные комментарии не могут быть вложенными (т.е. одни комментарии внутри других):

Правило: Никогда не используйте вложенные комментарии.

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

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

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

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

Или:

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

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

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

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

(По коду это и так понятно)

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

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

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

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

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

(Теперь понятно!)

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

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

Или:

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

Подытожим:

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

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

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

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


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

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

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

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

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

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

Закомментировано символами однострочного комментария:

Закомментировано символами многострочного комментария:

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

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

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

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

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

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

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

Звёзд: 1Звёзд: 2Звёзд: 3Звёзд: 4Звёзд: 5 (1 378 оценок, среднее: 4,94 из 5)
Загрузка...

Комментариев: 28

  1. Илья:

    Очень понятно все. Думаю для базы этого достаточно, создал базу — идешь в учебники. В учебниках для новичков ничего не понятно, а тут все понятно. Спасибо за понятное объяснение материала!

    1. Фото аватара Юрий:

      Пожалуйста)

  2. Мария:

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

    1. Фото аватара Юрий:

      Пожалуйста)) Очень круто, что Равесли оказался Вам полезным))

  3. Сергей:

    Огромная благодарность за Ваш труд. Мне скоро 50, программировал станки с ЧПУ (В Германии) и многим другими направлениями занимался и занимаюсь, еще в школе говорили, в программировании будущее. Ну вот, до меня наконец-то дошло, что пора обратить внимание на знаки судьбы.

    1. Фото аватара Юрий:

      Пожалуйста)

  4. Subado:

    Спасибо вам, Юрий! В ваших статьях очень много полезной информации. Я изучаю C++ уже 5 месяцев, и ваши статьи помогают заполнить пробелы в теоретической части языка

  5. Виктория:

    И за эти статьи тоже спасибо огромное! Очень помогает подготовиться к экзу по АиП и заполнить пробелы 😉

    1. Фото аватара Юрий:

      Пожалуйста) Рад, что Равесли оказался для вас полезным)

  6. Max:

    А можете написать уроки по языку программирование Haskell или Erlang Ocaml

    1. Фото аватара Юрий:

      Если бы это было так просто, как написать комментарий — то уже были бы уроки к 20 языкам программирования)

  7. Юрий:

    Спасибо Вам за этот прекрасный и доступный курс. Я сам преподаватель информатики и этот курс читаю с огромным удовольствием!!! Спасибо Вам за Ваш громадный и прекрасный курс!!!

    1. Фото аватара Юрий:

      Пожалуйста 🙂

  8. Александр:

    А если необходимо символы /* */ запихнуть в строковую переменную, то как это сделать правильно, не сломая его?

    1. Фото аватара Дмитрий Бушуев:

      Используйте символ обратного слэша — \
      Например:

  9. APTEM:

    Зачем заключать нерабочий код в комментарий?
    Помойму легче скопировать его и куда нибудь сохранить.. Потом достать вставить и доделать

    1. Сергей:

      1)чтоб был под носом (никуда его не переносить)
      2)удобство — гораздо проще кликнуть пару слешей или обозначать область /* */ . Чем держать в дампе или переносить куда-либо.

  10. Андрей:

    Мне 50, я одинок, имею кучу времени, некую давнюю мечту — что то сделать самому… — И вот: С++ мне в помощь!!
    Очень благодарен Автору! Вы даёте импульс жить дальше!.

    1. Фото аватара Юрий:

      Приятно, что оказался вам полезен 🙂

  11. Demien:

    Ты забыл о третьем виде коментариев — тройной слеш.

  12. Александр Казаков:

    Новое понимание комментария. Спасибо! Это другой взгляд или взгляд с другой стороны.

  13. Testik:

    В третьей части урока мы создаём второй уровень для игры Кот в лабиринте и закрепляем команды Scratch для реализации движения спрайтов по координатам.

  14. Эзиз:

    Самая легкая тема в программирований)))

    1. Наталья:

      Написание хороших комментариев — одна из наиболее сложных задач в программировании, а отнюдь не самая лёгкая. Спасибо автору за грамотное изложение того, что именно надо писать в комментариях, и за наглядные примеры.

  15. Feliz:

    А почему "ravesli" ?

    1. Фото аватара Юрий:

      Просто так. Название ни к чему не привязано.

      1. Георгий:

        Я то думаю что так сложно запомнить название , проще курс запомнить

  16. Денис:

    Спасибо, узнал, что можно "закомментировать"

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

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