Комментарий – это заметка, удобная для чтения программисту, которая вставляется непосредственно в исходный код программы. Комментарии игнорируются компилятором и предназначены только для использования программистом.
В C++ есть два разных стиля комментариев, которые служат одной цели: помочь программистам каким-то образом документировать код.
Однострочные комментарии
Однострочный комментарий C++ начинается с символов // , которые указывают компилятору игнорировать всё, от символов // до конца строки. Например:
std::cout
Обычно однострочный комментарий используется для быстрого комментария к одной строке кода.
std::cout
Наличие комментариев справа от строки может затруднить чтение и кода, и комментария, особенно если строка длинная. Если строки достаточно короткие, комментарии можно просто выровнять (обычно по позиции табуляции), например:
std::cout
Однако, если строки длинные, размещение комментариев справа может сделать ваши строки очень длинными. В этом случае однострочные комментарии часто помещаются над строкой, которую они комментируют:
Комментарии в HTML. Как в HTML сделать комментарий — основные правила
// std::cout живет в библиотеке iostream std::cout
Примечание автора
Приведенные выше инструкции представляют собой одну из наших первых встреч с фрагментами кода. Поскольку фрагменты не являются полноценными программами, они не могут быть скомпилированы сами по себе. Они нужны, чтобы кратко продемонстрировать конкретные концепции.
Если вы хотите скомпилировать фрагмент кода, вам нужно превратить его в полную программу, чтобы она могла скомпилироваться. Обычно эта программа будет выглядеть примерно так:
#include int main() < // Замените эту строку фрагментом кода, который вы хотите скомпилировать return 0; >
Многострочные комментарии
Пары символов /* и */ отмечают многострочный комментарий в стиле C. Всё, что находится между этими символами, игнорируется.
/* Это многострочный комментарий. Эта строка будет проигнорирована. И эта тоже. */
Поскольку всё, что находится между этими символами, игнорируется, вы иногда можете увидеть, как программисты «украшают» свои многострочные комментарии:
/* Это многострочный комментарий. * выровненные звездочки слева * могут облегчить чтение */
Комментарии в многострочном стиле не могут быть вложенными. Следовательно, результаты следующего кода могут быть неожиданными:
/* Это многострочный /* комментарий */ не внутри комментария */ // Приведенный выше комментарий заканчивается первым */, а не вторым */
Когда компилятор попытается скомпилировать этот код, он проигнорирует все, от первого /* до первого */ . Поскольку фрагмент « это не внутри комментария */ » не считается частью комментария, компилятор попытается скомпилировать его. Это неизбежно приведет к ошибке компиляции.
Это то место, где использование подсветки синтаксиса может быть действительно полезным, поскольку различная окраска текста комментария должна прояснить, что считается частью комментария, а что нет.
ДЛЯ ЧЕГО НУЖНЫ ПРОГРАММЫ НАСТАВНИЧЕСТВА И АДАПТАЦИИ? Руслан Тарусин — АвтоГермес. АвтоБосс Клуб
Предупреждение
Не используйте многострочные комментарии внутри других многострочных комментариев. Обертывание однострочных комментариев внутри многострочных комментариев допускается.
Правильное использование комментариев
Обычно комментарии используются для трех вещей. Во-первых, для заданной библиотеки, программы или функции комментарии лучше всего использовать для описания того, что делает библиотека, программа или функция. Обычно они размещаются в верхней части файла или библиотеки или непосредственно перед функцией. Например:
// Эта программа вычисляет итоговую оценку учащегося на основе результатов теста и домашних заданий.
// Эта функция использует метод Ньютона для аппроксимации корня данного уравнения.
// Следующие строки генерируют случайный элемент в зависимости от редкости, уровня и весового коэффициента.
Все эти комментарии дают читателю хорошее представление о том, что пытается выполнить библиотека, программа или функция, не обращая внимания на реальный код. Пользователь (возможно, кто-то другой или вы, если вы пытаетесь повторно использовать код, который вы написали ранее) может сразу определить, соответствует ли код тому, что он или она пытается выполнить. Это особенно важно при работе в команде, где не все знакомы со всем кодом.
Во-вторых, внутри библиотеки, программы или функции, описанной выше, можно использовать комментарии, чтобы описать, как код будет достигать своей цели.
/* Чтобы подсчитать итоговую оценку, мы суммируем все взвешенные промежуточные баллы и баллы за домашнее задание, а затем делим на количество баллов, чтобы определить процент, который используется для расчета буквенной оценки. */
// Чтобы сгенерировать случайный элемент, мы сделаем следующее: // 1) помещаем все элементы необходимой редкости в список; // 2) рассчитываем вероятность для каждого элемента на основе уровня и весового коэффициента; // 3) выбираем случайное число; // 4) выясняем, какому элементу соответствует это случайное число; // 5) возвращаем соответствующий элемент.
Эти комментарии дают пользователю представление о том, как код будет достигать своей цели, без необходимости понимать, что делает каждая отдельная его строка.
В-третьих, на уровне инструкций следует использовать комментарии, чтобы описать, почему код что-то делает. Комментарий плохой инструкции объясняет, что делает код. Если вы когда-нибудь напишете настолько сложный код, который требует комментария, чтобы объяснить, что делает инструкция, вам, вероятно, лучше переписать свою инструкцию, а не комментировать ее.
Вот несколько примеров плохих комментариев к строке и хороших комментариев к инструкции.
// Устанавливаем дальность прицела на 0 sight = 0;
Причина: мы уже видим, что прицел (sight) устанавливается на 0, посмотрев на инструкцию.
// Игрок только что выпил зелье слепоты и ничего не видит sight = 0;
Причина: теперь мы знаем, почему прицел игрока установлен на 0.
// Рассчитываем стоимость предметов cost = quantity * 2 * storePrice;
Причина: мы видим, что это расчет стоимости, но почему количество умножается на 2?
// Здесь нам нужно умножить количество на 2, потому что они покупаются парами cost = quantity * 2 * storePrice;
Причина: Теперь мы знаем, почему эта формула имеет смысл.
Программистам часто приходится выбирать между решением задачи одним или другим способом. Комментарии – отличный способ напомнить себе (или рассказать кому-то другому), почему вы приняли одно решение вместо другого.
// Мы решили использовать связный список вместо массива, потому что // вставка в массивы слишком медленна.
// Мы собираемся использовать метод Ньютона, чтобы найти корень числа, потому что // нет детерминированного способа решения этих уравнений.
Наконец, комментарии должны быть написаны таким образом, чтобы иметь смысл для тех, кто не знает, что делает код.
Часто программист говорит: «Совершенно очевидно, что он делает! Я ни за что не забуду об этом,». Угадайте, что? Это не очевидно, и вы удивитесь, как быстро вы забудете. 🙂 Вы (или кто-то другой) поблагодарите вас позже за то, что вы написали, что, как и почему делается в вашем коде на человеческом языке. Читать отдельные строки кода легко.
Понимание того, для чего они предназначены, – нет.
Лучшая практика
Обильно комментируйте свой код и пишите свои комментарии, как если бы разговаривали с кем-то, кто не знает, что делает код. Не думайте, что вы вспомните, почему вы сделали конкретный выбор.
Примечание автора
На протяжении всей остальной части этой серии руководств мы будем использовать комментарии внутри фрагментов кода, чтобы привлечь ваше внимание к конкретным вещам или помочь проиллюстрировать, как всё работает (обеспечивая при этом компиляцию программ). Проницательные читатели заметят, что по вышеуказанным стандартам большинство этих комментариев ужасны. 🙂 Читая остальные руководства, имейте в виду, что комментарии служат намеренно образовательной цели, а не пытаются продемонстрировать, как выглядят хорошие комментарии.
Закомментирование кода
Преобразование одной или нескольких строк кода в комментарий называется закомментированием кода. Это предоставляет удобный способ (временно) исключить фрагменты вашего кода из включения в скомпилированную программу.
Чтобы закомментировать одну строку кода и временно превратить эту строку кода в комментарий, просто используйте однострочный комментарий // :
std::cout
// std::cout
Чтобы закомментировать блок кода и временно превратить этот блок кода в комментарий, используйте // в нескольких строках кода или многострочный комментарий /* */ .
std::cout
// std::cout
/* std::cout
Есть несколько причин, по которым вы можете захотеть это сделать:
- Вы работаете над новым фрагментом кода, который еще не компилируется, и вам нужно запустить программу. Компилятор не позволит вам скомпилировать код, если есть ошибки компиляции. Комментирование кода, который не компилируется, позволит программе скомпилироватьсь, чтобы вы могли ее запустить. Когда вы будете готовы, вы сможете раскомментировать код и продолжить работу над ним.
- Вы написали новый код, который компилируется, но работает некорректно, и у вас нет времени исправить его. Комментирование неработающего кода гарантирует, что он не будет выполняться и не вызовет проблемы, пока вы не исправите его.
- Поиск источника ошибки. Если программа не дает желаемых результатов (или дает сбой), иногда может быть полезно отключить части вашего кода, чтобы посмотреть, можете ли вы определить причину, по которой она работает некорректно. Если вы закомментировали одну или несколько строк кода, и ваша программа начинает работать должным образом (или перестает давать сбой), скорее всего, то, что вы в последний раз закомментировали, было частью проблемы. Затем вы можете выяснить, почему эти строки кода вызывают проблему.
- Вы хотите заменить один фрагмент кода другим фрагментом кода. Вместо того чтобы просто удалять исходный код, вы можете закомментировать его и оставить для справки, пока не убедитесь, что новый код работает правильно. Убедившись, что ваш новый код работает, вы можете удалить старый закомментированный код. Если вам не удается заставить новый код работать, вы всегда можете удалить новый код и раскомментировать старый код, чтобы вернуться к тому, что было раньше.
Закомментирование кода – обычное дело при разработке, поэтому многие IDE поддерживают комментирование выделенного участка кода. Доступ к этой функции зависит от IDE.
Для пользователей Visual Studio
Вы можете закомментировать или раскомментировать выделенный фрагмент с помощью меню Правка (Edit) → Дополнительно (Advanced) → Закомментировать выделенный фрагмент (Comment Selection) или Раскомментировать выделенный фрагмент (Uncomment Selection).
Для пользователей Code::Blocks
Вы можете закомментировать или раскомментировать выделенный фрагмент с помощью меню Edit (Правка) → Comment (Комментарий) или Uncomment (Раскомментировать) или Toggle comment (Переключить комментарий) или любой другой инструмент для комментирования.
Совет
Если для своих обычных комментариев вы всегда используете однострочные комментарии, вы всегда можете использовать многострочные комментарии, чтобы без конфликтов комментировать свой код. Если вы используете многострочные комментарии для документирования кода, то закомментирование кода может стать более сложной задачей.
Если вам нужно закомментировать блок кода, содержащий многострочные комментарии, вы также можете рассмотреть возможность использования директивы препроцессора #if 0 , которую мы обсуждаем в уроке «2.9 – Знакомство с препроцессором».
Резюме
- На уровне библиотеки, программы или функции используйте комментарии, чтобы описать что делается.
- Внутри библиотеки, программы или функции используйте комментарии, чтобы описать, как это сделать.
- На уровне инструкции используйте комментарии, чтобы объяснить, почему.
Источник: radioprog.ru
Что такое комментарии и зачем они нужны?
Возможно вы заметили, что в листингах из примеров встречается не только код программ, но и мои пояснения написанные после «//». Это комментарии . Они предназначены для того, чтобы пояснять какую-нибудь сложную и непонятную часть вашей программы. Кроме того, иногда их используют, чтобы на время отключить какую-то часть кода.
Это возможно потому, что всё что записано в комментарии компилятор игнорирует. Если быть точнее то к тому времени, как компилятор начнёт обрабатывать код программы все комментарии будут уже удалены. Поэтому туда можно писать всё что угодно.
Рис.1. Пример использования комментария в программе. (Язык Fortran)
В языке Си есть два вида комментариев. Первый вид тот, который я использую в коде. Такой комментарий называет однострочным. Он действует с того момента как появился и до конца текущей строки. Есть ещё и многострочный комментарий.
Начало такого комментария обозначается последовательностью «/*», а конец — «*/». Всё, что будет записано между этими двумя последовательностями символов не будет восприниматься компилятором. Обычно многострочные комментарии используют для описания больших кусков кода, очень сложных для понимания функций, для указания авторства, для исключения большого куска кода из программы и т.д.
Вы спросите а зачем нужно отключать куски кода программы? Иногда это нужно для того, чтобы найти ошибку в программе или проверить как работают отдельные её части. Если просто удалить код, то потом его придётся писать заново, а так, закомментировал на время, а потом обратно раскомментировал, когда потребовалось. Когда вы начнёте писать более менее большие программы, тогда вы воочию убедитесь в пользе.
Комментарии пишутся программистами для других программистов, которые в будущем будут читать/изменять этот код. Но даже если вы пишите код сугубо в личных целях, то не рекомендую вам брезговать оставлять комментарии. По прошествию нескольких месяцев бывает очень трудно вспомнить, что же ты тут такое делал и почему именно так делал, а не иначе.
Комментарии в коде могут быть как очень смешными:
// Магия. Не трогать. //Этот код отстой, и мы оба это знаем. //Так что двигайся дальше, а идиотом ты назовешь меня потом. // Дорогой я_из_будущего!
Пожалуйста, прости меня за этот код. // Если я еще раз увижу такое, мне придется начать носить на работу оружие. /* Если это условие когда-нибудь выполнится, пожалуйста, сообщите мне по тел. ххх-ххх-ххх за вознаграждение. */ // пьян, исправить позже // Когда я начинал это писать, только Бог и я понимали, что я делаю // Сейчас остался только Бог
//Пожалуйста, работай // Я не несу ответственности за этот код. // Они меня заставили написать его против моей воли. /* Если вы читаете эти строки, значит вам поручили мой предыдущий проект. Я очень, очень сочувствую вам. Удачи. */
Сохрани в закладки или поддержи проект.
Практика
- Откройте программу «Hello, World». Попробуйте закомментировать строчку printf(«Hello, World!n»); Как вы думаете, как изменится работа программы? Проверьте свое предположение, скомпилировав и запустив эту программу.
- Закомментируйте в следующей программе некоторые строки так, чтобы на экране появился следующий текст:
The Matrix has you.
Follow the white rabbit.
Программа для изменения
#include int main (void) < while (1 >0) < printf(«Wake up, Neo. nn»); >if (0 > 1) < printf(«The Matrix has you. nn»); >printf(«Follow the white rabbit. n»); return 0; >
Не бойтесь новый непонятных команд! С ними мы ещё разберёмся. =) Программистам часто приходится работать с кодом, в котором они не всё до конца понимают.
#include #include //библиотека с локализацией, чтобы были доступны русские буквы int main(void) < setlocale(LC_ALL, «»); //подключаем локализацию // char str1[]= «Поздравляю! Вы справились с задачей!»; // for (int i=0; i
Дополнительные материалы
- Подборки смешных и не очень комментариев: раз, два.
Увидели смешной комментарий? Напишите его в комменты. - Немного о том, как и для чего [не]нужно писать комментарии
Источник: youngcoder.ru
Комментирование в C: зачем ставить комментарии в коде своей программы
Комментарии в С — это специальные пояснительные строки, которые помогают зафиксировать, а потом через время понять смысл написанного кода. Комментарии рассчитаны для людей и никак не воспринимаются компилятором или интерпретатором.
Комментарии в С могут писаться в одну или несколько строк. В зависимости от этого синтаксис комментариев будет отличаться, об этом чуть ниже.
Комментарии в С
В этой статье мы поговорим о том, что такое комментирование в С, хотя, в принципе , подход к написанию комментариев во всех языках программирования будет одинаковым. Все , что будет отличаться , — это синтаксис написания тех или иных комментариев.
Для чего нужны комментарии в С?
- Чтобы помочь в случае чего разобраться с написанным кодом. Ситуации могут быть разные: может , вы вернетесь к своему коду через год , и , если не будет комментариев , вы не поймете , что вы там писали ; возможно , ваш код будут дорабатывать другие программисты , и комментарии помогут его быстрее понять.
- Чтобы не запутаться при разработке собственных библиотек, функций, методов и переменных.
- Для тестирования программы. В случае обнаружения ошибок комментарии в С помогут быстрее найти , откуда они происходят.
- Чтобы описать сложные алгоритмы или формулы. Если ваша программа завязана на сложных математических расчетах, то комментарии будут незаменимы.
Как оформить комментарии в С?
- Однострочныекомментарии в С обозначаются двумя наклонными линиями «//» только в начале самого комментария.
- Многострочные комментарии в С обозначаются с двух сторон, отмечая начало и конец комментария. В качестве обозначения таких комментариев применяют сочетание наклонной линии и «звездочки». Многострочный комментарий будет выглядеть так: « /*многострочные комментарии в С*/ ».
По каким правилам пишутся комментарии в С?
Изначально можно подумать, что раз комментарии в С не читаются интерпретаторами и компиляторами, то можно их писать где хочешь и сколько хочешь, просто правильно оформляя. Так никто не запрещает поступать, но есть общепринятые рекомендации по написани ю комментариев. Лучше и х придерживаться, чтобы ваш код был не только эффективным, но и правильно оформленным.
Рекомендации о том, как писать комментарии в С:
- Место написания. Комментарии в С рекомендуется писать справа от строки, к которой они относятся, если комментарий короткий ; и сверху над кодом, к которому они относятся, если комментарий многострочный.
- Область комментирования. Комментируется не все подряд, а только основные и значимые части кода: функция, модуль, константа, глобальная переменная, интерфейс, класс и др.
- Размер комментария. Комментарии в С не должны выглядеть как целые поэмы. Нужно писать максимально коротко и только по делу. Любой комментарий, который не несет смысла, не должен присутствовать в коде.
Кстати, все комментарии в С по смысловой нагрузке можно разделить на 2 группы:
- Для пояснения.Сюда включают все комментарии в С, которые разъясняют логику поведения кода, функции, алгоритма и т. д. Наличие комментариев такого рода регламентируются самим разработчиком. Именно они обеспечивают дальнейшее удобство взаимодействия с кодом и пояснение его составляющих.
- Для документирования.Эта группа комментариев является обязательной. Такие комментарии в С располагаются в самом начале документа с кодом. Они несут в себе информацию о разработчике, о разрабатываемой программе, об используемых библиотеках и других параметрах, влияющих на работоспособность всего документа. Это своего рода предисловие ко всей программ е , которое несет в себе основной посыл и общее представление о само м программном обеспечении. Иногда генерация подобных комментариев в С может происходить в автоматическом режиме, для этого применяют специальные генераторы. Для языка С таким генератором является «doxygen».
Когда нужны комментарии в С, а когда — нет?
Иногда комментариев для документирования бывает недостаточно , и поэтому разработчики добавляют в документ комментарии для пояснения. Это делается для того, чтобы облегчить дальнейшее взаимодействие с кодом, чтобы точнее пояснить, почему в коде написано именно так, а не иначе.
Однако при этом не стоит просто нагружать документ ненужными комментариями. То есть не т необходимости комментировать то, что и так очевидно. Пример того, как делать не надо:
/*
Для переменной age указываем значение 45
*/
int age=45
То есть тут и так все понятно, поэтому не нужно засорять код такими комментариями. Изначально важно стремиться к тому, чтобы писать код, не требующий подробного комментирования. А если комментарий и пишется, то только по делу.
Заключение
Комментарии в С — это еще один инструмент разработчика, чтобы сделать разработку программ легче и понятне й . Они очень помогают, когда происходит командная работа над большими проектами и над одной и той же частью программы могут работать разные люди в разное время. Но в то же время комментариев не должно быть в переизбытке.
Нужно уметь соблюдать баланс, чтобы ваш код действительно был эффективным и пояснительным. Ведь если будет недостаточно комментариев, то его через время будет сложно понять. А если комментарии в С будут пояснять каждую мелочь, то сам код среди обилия комментариев будет сложно найти. И разработчик будет тратить больше времени на написание комментариев, чем на сам код, а это неправильно.
Запомните! Лучше писать простой и понятный код, чем писать непонятный и запутанный, но с большим количеством комментариев.