Комментарии
Все, что находится в однострочном комментарии — от // до конца строки — игнорируется компилятором, как и весь многострочный комментарий, расположенный между /* и */. Очевидно, что в многострочном комментарии не может присутствовать комбинация */, поскольку она будет трактоваться как конец комментария.
Многострочный комментарий можно помещать в одну строку кода:
Встроенные комментарии вроде этого нужно применять осторожно, потому что они могут ухудшить читабельность кода. Однако они удобны при отладке, скажем, когда необходимо временно попробовать запустить программу с указанным другим значением:
Символы комментария, включенные в строковый литерал, конечно же, трактуются как обычные символы:
Документация XML
В дополнение к комментариям в стиле C, проиллюстрированным выше, в C# имеется очень искусное средство, на которое я хочу обратить особое внимание: способность генерировать документацию в формате XML на основе специальных комментариев. Это однострочные комментарии, начинающиеся с трех слешей (///) вместо двух. В таких комментариях можно размещать XML-дескрипторы, содержащие документацию по типам и членам типов, используемым в коде.
XML-дескрипторы, распознаваемые компилятором, перечислены в следующей таблице:
| Дескриптор | Описание |
|---|---|
| Помечает текст в строке как код | |
| Помечает множество строк как код | |
| Помечает пример кода | |
| Документирует класс исключения (синтаксис проверяется компилятором) | |
| Включает комментарии из другого файла документации (синтаксис проверяется компилятором) | |
| Вставляет список в документацию | |
| Указывает, что слово является параметром метода (синтаксис проверяется компилятором) | |
| Документирует доступ к члену (синтаксис проверяется компилятором) | |
| Добавляет описание члена | |
| Документирует возвращаемое методом значение | |
| Представляет перекрестную ссылку на другой параметр (синтаксис проверяется компилятором) | |
| Представляет раздел «see also» («смотреть также») в описании (синтаксис проверяется компилятором) | |
| Представляет краткий итог о типе или члене | |
| Описывает свойство |
Чтобы увидеть, как это работает, рассмотрим пример кода, в который добавим некоторые XML-комментарии:
Компилятор C# может извлекать XML-элементы из специальных комментариев и использовать их для генерации файлов XML. Чтобы заставить компилятор сгенерировать XML-документацию для сборки, указывается опция /doc вместе с именем файла, который должен быть создан:
Урок №9. Комментарии
Обновл. 11 Сен 2021 |
Комментарий — это строка (или несколько строк) текста, которая вставляется в исходный код для объяснения того, что делает код. В языке C++ есть 2 типа комментариев: однострочные и многострочные.
Однострочные комментарии
Как правило, однострочные комментарии используются для объяснения одной строчки кода:
Размещая комментарии справа от кода, мы затрудняем себе как чтение кода, так и чтение комментариев. Следовательно, однострочные комментарии лучше размещать над строками кода:
Многострочные комментарии
Так как всё, что находится между звёздочками, — игнорируется, то иногда вы можете наблюдать следующее:
Многострочные комментарии не могут быть вложенными (т.е. одни комментарии внутри других):
Правило: Никогда не используйте вложенные комментарии.
Как правильно писать комментарии?
Во-первых, на уровне библиотек/программ/функций комментарии отвечают на вопрос «ЧТО?»: «Что делают эти библиотеки/программы/функции?». Например:
Все эти комментарии позволяют понять, что делает программа, без необходимости смотреть на исходный код. Это особенно важно специалистам, работающим в команде, где не каждый специалист будет знаком со всем имеющимся кодом.
Во-вторых, внутри библиотек/программ/функций комментарии отвечают на вопрос «КАК?»: «Как код выполняет задание?». Например:
Эти комментарии позволяют читателю понять, каким образом код выполняет поставленное ему задание.
В-третьих, на уровне стейтментов (однострочного кода) комментарии отвечают на вопрос «ПОЧЕМУ?»: «Почему код выполняет задание именно так, а не иначе?». Плохой комментарий на уровне стейтментов объясняет, что делает код. Если вы когда-нибудь писали код, который был настолько сложным, что нужен был комментарий, который бы объяснял, что он делает, то вам нужно было бы не писать комментарий, а переписывать этот код.
Примеры плохих и хороших однострочных комментариев:
(По коду это и так понятно)
(Теперь мы знаем, ПОЧЕМУ зрение у игрока равно нулю)
(Да, мы видим, что здесь подсчет стоимости, но почему элементы делятся на 2?)
Программистам часто приходится принимать трудные решения по поводу того, каким способом решить проблему. А комментарии и существуют для того, чтобы напомнить себе (или объяснить другим) причину, почему вы написали код именно так, а не иначе.
И, наконец, комментарии нужно писать так, чтобы человек, который не имеет ни малейшего представления о том, что делает ваш код — смог в нем разобраться. Очень часто случаются ситуации, когда программист говорит: «Это же совершенно очевидно, что делает код! Я это точно не забуду!». Угадайте, что случится через несколько недель или даже дней? Это не совершенно очевидно, и вы удивитесь, как скоро вы забудете то, что делает ваш код. Вы (или кто-то другой) будете очень благодарны себе за то, что оставите комментарии, объясняя на человеческом языке что, как и почему делает ваш код. Читать отдельные строки кода — легко, понимать их логику и смысл — сложно.
Подытожим:
На уровне библиотек/программ/функций оставляйте комментарии, отвечая на вопрос «ЧТО?».
Внутри библиотек/программ/функций оставляйте комментарии, отвечая на вопрос «КАК?».
На уровне стейтментов оставляйте комментарии, отвечая на вопрос «ПОЧЕМУ?».
Закомментировать код
Закомментировать код — это конвертировать одну или несколько строк кода в комментарии. Таким образом, вы можете (временно) исключить часть кода из компиляции.
Закомментировано символами однострочного комментария:
Закомментировано символами многострочного комментария:
Есть несколько причин, почему следует использовать «закомментирование»:
Причина №1: Вы работаете над новой частью кода, которая пока что не рабочая, но вам нужно запустить программу. Компилятор не позволит выполнить программу, если в ней будут ошибки. Временное отделение нерабочего кода от рабочего комментированием позволит вам запустить программу. Когда код будет рабочий, то вы сможете его легко раскомментировать и продолжить работу.
Причина №2: Вы написали код, который компилируется, но работает не так, как нужно и сейчас у вас нет времени с этим возиться. Закомментируйте код, а затем, когда будет время, исправьте ошибки.
Причина №3: Поиск корня ошибки. Если вас не устраивают результаты работы программы (или вообще происходит сбой), полезно будет поочерёдно «отключать» части вашего кода, чтобы понять какие из них рабочие, а какие — создают проблемы. Если вы закомментируете одну или несколько строчек кода и программа начнет корректно работать (или пропадут сбои), шансы того, что последнее, что вы закомментировали, является ошибкой — очень велики. После этого вы сможете разобраться с тем, почему же этот код не работает так, как нужно.
Причина №4: Тестирование нового кода. Вместо удаления старого кода, вы можете его закомментировать и оставить для справки, пока не будете уверены в том, что ваш новый код работает так, как нужно. Как только вы будете уверены в новом коде, то сможете без проблем удалить старые фрагменты кода. Если же новый код у вас будет работать не так, как нужно, то вы сможете его удалить и откатиться к старому коду.
Примечание: Во всех следующих уроках я буду использовать комментарии в иллюстративных целях. Внимательные читатели смогут заметить, что по вышеуказанным стандартам большинство из этих комментариев будут плохими. Но помните, что использовать я их буду в образовательных целях, а не для демонстрации хороших примеров.
Комментирование в C: зачем ставить комментарии в коде своей программы
Комментарии в С — это специальные пояснительные строки, которые помогают зафиксировать, а потом через время понять смысл написанного кода. Комментарии рассчитаны для людей и никак не воспринимаются компилятором или интерпретатором.
Комментарии в С могут писаться в одну или несколько строк. В зависимости от этого синтаксис комментариев будет отличаться, об этом чуть ниже.
Комментарии в С
Для чего нужны комментарии в С?
Комментарии в С и в других языках программирования нужны:
Чтобы не запутаться при разработке собственных библиотек, функций, методов и переменных.
Чтобы описать сложные алгоритмы или формулы. Если ваша программа завязана на сложных математических расчетах, то комментарии будут незаменимы.
Как оформить комментарии в С?
Однострочные комментарии в С обозначаются двумя наклонными линиями «//» только в начале самого комментария.
Многострочные комментарии в С обозначаются с двух сторон, отмечая начало и конец комментария. В качестве обозначения таких комментариев применяют сочетание наклонной линии и «звездочки». Многострочный комментарий будет выглядеть так: « /*многострочные комментарии в С*/ ».
По каким правилам пишутся комментарии в С?
Изначально можно подумать, что раз комментарии в С не читаются интерпретаторами и компиляторами, то можно их писать где хочешь и сколько хочешь, просто правильно оформляя. Так никто не запрещает поступать, но есть общепринятые рекомендации по написани ю комментариев. Лучше и х придерживаться, чтобы ваш код был не только эффективным, но и правильно оформленным.
Рекомендации о том, как писать комментарии в С:
Место написания. Комментарии в С рекомендуется писать справа от строки, к которой они относятся, если комментарий короткий ; и сверху над кодом, к которому они относятся, если комментарий многострочный.
Область комментирования. Комментируется не все подряд, а только основные и значимые части кода: функция, модуль, константа, глобальная переменная, интерфейс, класс и др.
Размер комментария. Комментарии в С не должны выглядеть как целые поэмы. Нужно писать максимально коротко и только по делу. Любой комментарий, который не несет смысла, не должен присутствовать в коде.
Кстати, все комментарии в С по смысловой нагрузке можно разделить на 2 группы:
Для пояснения. Сюда включают все комментарии в С, которые разъясняют логику поведения кода, функции, алгоритма и т. д. Наличие комментариев такого рода регламентируются самим разработчиком. Именно они обеспечивают дальнейшее удобство взаимодействия с кодом и пояснение его составляющих.
Когда нужны комментарии в С, а когда — нет?
Однако при этом не стоит просто нагружать документ ненужными комментариями. То есть не т необходимости комментировать то, что и так очевидно. Пример того, как делать не надо:
Для переменной age указываем значение 45
То есть тут и так все понятно, поэтому не нужно засорять код такими комментариями. Изначально важно стремиться к тому, чтобы писать код, не требующий подробного комментирования. А если комментарий и пишется, то только по делу.
Заключение
Запомните! Лучше писать простой и понятный код, чем писать непонятный и запутанный, но с большим количеством комментариев.
Мы будем очень благодарны
если под понравившемся материалом Вы нажмёте одну из кнопок социальных сетей и поделитесь с друзьями.
Комментарии в C
Комментарий — это последовательность символов, которая начинается с косой черты и звездочки (/*). Компилятор воспринимает комментарий как один пробельный символ, в остальных случаях он игнорируется. Комментарии могут включать любое сочетание символов из представимого набора символов, который включает символы новой строки, но не включает разделитель конца комментария (*/). Комментарии могут занимать несколько строк, но не могут быть вложенными.
Они могут располагаться в любом месте, где допускается использование пробельных символов. Поскольку компилятор обрабатывает комментарий как один пробельный символ, его невозможно использовать в составе токена. Символы, которые находятся в комментарии, компилятор игнорирует.
Комментарии используются для документирования кода. В следующем примере компилятор принимает комментарий:
Комментарии в коде могут находиться в той же строке, что и оператор:
Перед функциями или программными модулями можно вставлять блоки комментариев с описаниями.
Поскольку комментарии не могут содержать вложенные комментарии, то следующий пример вызовет ошибку:
Хотя с помощью комментариев можно скрывать часть кода для тестирования, для этого есть полезная альтернатива: директивы препроцессора #if и #endif и условная компиляция. Дополнительные сведения см. в статье Preprocessor Directives (Директивы препроцессора) в справочника по препроцессору.
Блок, относящийся только к системам Microsoft
Компилятор Microsoft также поддерживает однострочные комментарии, перед которыми ставятся две косые черты ( // ). Если компиляция выполняется с параметром /Za (стандарт ANSI), то такие комментарии создают ошибки. Такие комментарии невозможно расширить до второй строки.
Комментарии, которые начинаются с двух косых черт ( // ), завершаются первым символом новой строки, перед которым не стоит escape-символ. В следующем примере перед символом новой строки стоит обратная косая черта ( \ ), которая создает escape-последовательность. В результате этого следующая строка обрабатывается компилятором как часть текущей строки. Дополнительные сведения см. в статье Escape Sequences (Escape-последовательности).
Поэтому оператор i++; скрыт комментарием.
В Microsoft C расширения Microsoft по умолчанию включены. Отключить их можно при помощи параметра /Za.
Завершение блока, относящегося только к системам Майкрософт
1.2 – Комментарии в C++
Комментарий – это заметка, удобная для чтения программисту, которая вставляется непосредственно в исходный код программы. Комментарии игнорируются компилятором и предназначены только для использования программистом.
В C++ есть два разных стиля комментариев, которые служат одной цели: помочь программистам каким-то образом документировать код.
Однострочные комментарии
Обычно однострочный комментарий используется для быстрого комментария к одной строке кода.
Наличие комментариев справа от строки может затруднить чтение и кода, и комментария, особенно если строка длинная. Если строки достаточно короткие, комментарии можно просто выровнять (обычно по позиции табуляции), например:
Однако, если строки длинные, размещение комментариев справа может сделать ваши строки очень длинными. В этом случае однострочные комментарии часто помещаются над строкой, которую они комментируют:
Примечание автора
Приведенные выше инструкции представляют собой одну из наших первых встреч с фрагментами кода. Поскольку фрагменты не являются полноценными программами, они не могут быть скомпилированы сами по себе. Они нужны, чтобы кратко продемонстрировать конкретные концепции.
Если вы хотите скомпилировать фрагмент кода, вам нужно превратить его в полную программу, чтобы она могла скомпилироваться. Обычно эта программа будет выглядеть примерно так:
Многострочные комментарии
Пары символов /* и */ отмечают многострочный комментарий в стиле C. Всё, что находится между этими символами, игнорируется.
Поскольку всё, что находится между этими символами, игнорируется, вы иногда можете увидеть, как программисты «украшают» свои многострочные комментарии:
Комментарии в многострочном стиле не могут быть вложенными. Следовательно, результаты следующего кода могут быть неожиданными:
Это то место, где использование подсветки синтаксиса может быть действительно полезным, поскольку различная окраска текста комментария должна прояснить, что считается частью комментария, а что нет.
Предупреждение
Не используйте многострочные комментарии внутри других многострочных комментариев. Обертывание однострочных комментариев внутри многострочных комментариев допускается.
Правильное использование комментариев
Обычно комментарии используются для трех вещей. Во-первых, для заданной библиотеки, программы или функции комментарии лучше всего использовать для описания того, что делает библиотека, программа или функция. Обычно они размещаются в верхней части файла или библиотеки или непосредственно перед функцией. Например:
Все эти комментарии дают читателю хорошее представление о том, что пытается выполнить библиотека, программа или функция, не обращая внимания на реальный код. Пользователь (возможно, кто-то другой или вы, если вы пытаетесь повторно использовать код, который вы написали ранее) может сразу определить, соответствует ли код тому, что он или она пытается выполнить. Это особенно важно при работе в команде, где не все знакомы со всем кодом.
Во-вторых, внутри библиотеки, программы или функции, описанной выше, можно использовать комментарии, чтобы описать, как код будет достигать своей цели.
Эти комментарии дают пользователю представление о том, как код будет достигать своей цели, без необходимости понимать, что делает каждая отдельная его строка.
В-третьих, на уровне инструкций следует использовать комментарии, чтобы описать, почему код что-то делает. Комментарий плохой инструкции объясняет, что делает код. Если вы когда-нибудь напишете настолько сложный код, который требует комментария, чтобы объяснить, что делает инструкция, вам, вероятно, лучше переписать свою инструкцию, а не комментировать ее.
Вот несколько примеров плохих комментариев к строке и хороших комментариев к инструкции.
Причина: мы уже видим, что прицел (sight) устанавливается на 0, посмотрев на инструкцию.
Причина: теперь мы знаем, почему прицел игрока установлен на 0.
Причина: мы видим, что это расчет стоимости, но почему количество умножается на 2?
Причина: Теперь мы знаем, почему эта формула имеет смысл.
Программистам часто приходится выбирать между решением задачи одним или другим способом. Комментарии – отличный способ напомнить себе (или рассказать кому-то другому), почему вы приняли одно решение вместо другого.
Наконец, комментарии должны быть написаны таким образом, чтобы иметь смысл для тех, кто не знает, что делает код. Часто программист говорит: «Совершенно очевидно, что он делает! Я ни за что не забуду об этом,». Угадайте, что? Это не очевидно, и вы удивитесь, как быстро вы забудете. 🙂 Вы (или кто-то другой) поблагодарите вас позже за то, что вы написали, что, как и почему делается в вашем коде на человеческом языке. Читать отдельные строки кода легко. Понимание того, для чего они предназначены, – нет.
Лучшая практика
Обильно комментируйте свой код и пишите свои комментарии, как если бы разговаривали с кем-то, кто не знает, что делает код. Не думайте, что вы вспомните, почему вы сделали конкретный выбор.
Примечание автора
На протяжении всей остальной части этой серии руководств мы будем использовать комментарии внутри фрагментов кода, чтобы привлечь ваше внимание к конкретным вещам или помочь проиллюстрировать, как всё работает (обеспечивая при этом компиляцию программ). Проницательные читатели заметят, что по вышеуказанным стандартам большинство этих комментариев ужасны. 🙂 Читая остальные руководства, имейте в виду, что комментарии служат намеренно образовательной цели, а не пытаются продемонстрировать, как выглядят хорошие комментарии.
Закомментирование кода
Преобразование одной или нескольких строк кода в комментарий называется закомментированием кода. Это предоставляет удобный способ (временно) исключить фрагменты вашего кода из включения в скомпилированную программу.
Чтобы закомментировать одну строку кода и временно превратить эту строку кода в комментарий, просто используйте однострочный комментарий // :
Есть несколько причин, по которым вы можете захотеть это сделать:
Закомментирование кода – обычное дело при разработке, поэтому многие IDE поддерживают комментирование выделенного участка кода. Доступ к этой функции зависит от IDE.
Для пользователей Visual Studio
Вы можете закомментировать или раскомментировать выделенный фрагмент с помощью меню Правка (Edit) → Дополнительно (Advanced) → Закомментировать выделенный фрагмент (Comment Selection) или Раскомментировать выделенный фрагмент (Uncomment Selection).
Для пользователей Code::Blocks
Вы можете закомментировать или раскомментировать выделенный фрагмент с помощью меню Edit (Правка) → Comment (Комментарий) или Uncomment (Раскомментировать) или Toggle comment (Переключить комментарий) или любой другой инструмент для комментирования.
Совет
Если для своих обычных комментариев вы всегда используете однострочные комментарии, вы всегда можете использовать многострочные комментарии, чтобы без конфликтов комментировать свой код. Если вы используете многострочные комментарии для документирования кода, то закомментирование кода может стать более сложной задачей.
