Практически все языки программирования позволяют оставлять в коде комментарии. Они никак не используются кодом и нужны исключительно для людей: чтобы программист оставлял пометки для себя и для других программистов. Комментарии в C# бывают трёх видов:
Однострочные комментарии начинаются с // . После этих двух символов может следовать любой текст, вся строчка не будет анализироваться и исполняться.
Комментарий может занимать всю строчку:
// For Winterfell!
или может находиться на строчке после какого-нибудь кода:
Console.WriteLine(«I am the King»); // => For Lannisters!
Многострочные комментарии начинаются с /* и заканчиваются на */ . Принято каждую строчку начинать с символа * , хотя технически это и не обязательно.
/* * The night is dark and * full of terrors. */ Console.WriteLine(«I am the King»); // => I am the King
Документирующие комментарии для каждой строчки используют /// .
Документирующие комментарии, являясь, по сути, подвидом однострочных, несут дополнительную функцию – добавляют подсказки к коду для внешних пользователей нашего кода. Мы поговорим о них позже – когда разберём классы и методы.
10 ФИШЕК YOUTUBE, которые мало кто знает
Задание
Создайте однострочный комментарий с текстом: You know nothing, Jon Snow!.
Упражнение не проходит проверку — что делать?
Если вы зашли в тупик, то самое время задать вопрос в «Обсуждениях». Как правильно задать вопрос:
- Обязательно приложите вывод тестов, без него практически невозможно понять что не так, даже если вы покажете свой код. Программисты плохо исполняют код в голове, но по полученной ошибке почти всегда понятно, куда смотреть.
В моей среде код работает, а здесь нет
Тесты устроены таким образом, что они проверяют решение разными способами и на разных данных. Часто решение работает с одними входными данными, но не работает с другими. Чтобы разобраться с этим моментом, изучите вкладку «Тесты» и внимательно посмотрите на вывод ошибок, в котором есть подсказки.
Мой код отличается от решения учителя
Это нормально , в программировании одну задачу можно выполнить множеством способов. Если ваш код прошел проверку, то он соответствует условиям задачи.
В редких случаях бывает, что решение подогнано под тесты, но это видно сразу.
Прочитал урок — ничего не понятно
Создавать обучающие материалы, понятные для всех без исключения, довольно сложно. Мы очень стараемся, но всегда есть что улучшать. Если вы встретили материал, который вам непонятен, опишите проблему в «Обсуждениях». Идеально, если вы сформулируете непонятные моменты в виде вопросов. Обычно нам нужно несколько дней для внесения правок.
Кстати, вы тоже можете участвовать в улучшении курсов: внизу есть ссылка на исходный код уроков, который можно править прямо из браузера.
Источник: code-basics.com
Авторские права на Ютубе: использование чужих видео на своём YouTube-канале
Пример добавления комментариев на 15 языках программирования
Давайте узнаем, что такое комментарии и почему они важны в программировании.
Урок №9. Комментарии
Комментарий — это строка (или несколько строк) текста, которая вставляется в исходный код для объяснения того, что делает код. В языке C++ есть 2 типа комментариев: однострочные и многострочные.
Однострочные комментарии
Однострочные комментарии — это комментарии, которые пишутся после символов // . Они пишутся в отдельных строках и всё, что находится после этих символов комментирования, — игнорируется компилятором, например:
Как правило, однострочные комментарии используются для объяснения одной строчки кода:
Размещая комментарии справа от кода, мы затрудняем себе как чтение кода, так и чтение комментариев. Следовательно, однострочные комментарии лучше размещать над строками кода:
// cout и endl находятся в библиотеке iostream
// теперь уже легче читать
Многострочные комментарии
Многострочные комментарии — это комментарии, которые пишутся между символами /* */ . Всё, что находится между звёздочками, — игнорируется компилятором:
/* Это многострочный комментарий.
Эта строка игнорируется
и эта тоже. */
Так как всё, что находится между звёздочками, — игнорируется, то иногда вы можете наблюдать следующее:
/* Это многострочный комментарий.
* Звёздочки слева
* упрощают чтение текста
Многострочные комментарии не могут быть вложенными (т.е. одни комментарии внутри других):
/* Это многострочный /* комментарий */ а это уже не комментарий * /
// Верхний комментарий заканчивается перед первым */, а не перед вторым */
Правило: Никогда не используйте вложенные комментарии.
Как правильно писать комментарии?
Во-первых, на уровне библиотек/программ/функций комментарии отвечают на вопрос «ЧТО?» : «Что делают эти библиотеки/программы/функции?». Например:
// Эта программа вычисляет оценку студента за семестр на основе его оценок за модули
// Эта функция использует метод Ньютона для вычисления корня функции
// Следующий код генерирует случайное число
Все эти комментарии позволяют понять, что делает программа, без необходимости смотреть на исходный код. Это особенно важно специалистам, работающим в команде, где не каждый специалист будет знаком со всем имеющимся кодом.
Во-вторых, внутри библиотек/программ/функций комментарии отвечают на вопрос «КАК?» : «Как код выполняет задание?». Например:
/ * Для расчета итоговой оценки ученика, мы складываем все его оценки за уроки и домашние задания,
а затем делим получившееся число на общее количество оценок.
Таким образом, мы получаем средний балл ученика. */
// Чтобы получить рандомный (случайный) элемент, мы выполняем следующее:
// 1) Составляем список всех элементов.
// 2) Вычисляем среднее значение для каждого элемента, исходя из его веса, цвета и цены.
// 3) Выбираем любое число.
// 4) Определяем соответствие элемента случайно выбранному числу.
// 5) Возвращаем случайный элемент.
Эти комментарии позволяют читателю понять, каким образом код выполняет поставленное ему задание.
В-третьих, на уровне стейтментов (однострочного кода) комментарии отвечают на вопрос «ПОЧЕМУ?» : «Почему код выполняет задание именно так, а не иначе?». Плохой комментарий на уровне стейтментов объясняет, что делает код. Если вы когда-нибудь писали код, который был настолько сложным, что нужен был комментарий, который бы объяснял, что он делает, то вам нужно было бы не писать комментарий, а переписывать этот код.
Примеры плохих и хороших однострочных комментариев :
// Присваиваем переменной sight значение 0
(По коду это и так понятно)
// Игрок выпил зелье слепоты и ничего не видит
(Теперь мы знаем, ПОЧЕМУ зрение у игрока равно нулю)
// Рассчитываем стоимость элементов
cost = items / 2 * storePrice ;
(Да, мы видим, что здесь подсчет стоимости, но почему элементы делятся на 2?)
// Нам нужно разделить все элементы на 2, потому что они куплены по парам
cost = items / 2 * storePrice ;
Программистам часто приходится принимать трудные решения по поводу того, каким способом решить проблему. А комментарии и существуют для того, чтобы напомнить себе (или объяснить другим) причину, почему вы написали код именно так, а не иначе.
// Мы решили использовать список вместо массива,
// потому что массивы осуществляют медленную вставку.
// Мы используем метод Ньютона для вычисления корня функции,
// так как другого детерминистического способа решения этой задачи — нет.
И, наконец, комментарии нужно писать так, чтобы человек, который не имеет ни малейшего представления о том, что делает ваш код — смог в нем разобраться. Очень часто случаются ситуации, когда программист говорит: «Это же совершенно очевидно, что делает код! Я это точно не забуду!». Угадайте, что случится через несколько недель или даже дней?
Это не совершенно очевидно, и вы удивитесь, как скоро вы забудете то, что делает ваш код. Вы (или кто-то другой) будете очень благодарны себе за то, что оставите комментарии, объясняя на человеческом языке что, как и почему делает ваш код. Читать отдельные строки кода — легко, понимать их логику и смысл — сложно.
На уровне библиотек/программ/функций оставляйте комментарии, отвечая на вопрос « ЧТО?».
Внутри библиотек/программ/функций оставляйте комментарии, отвечая на вопрос « КАК?».
На уровне стейтментов оставляйте комментарии, отвечая на вопрос « ПОЧЕМУ?» .
Закомментировать код
Закомментировать код — это конвертировать одну или несколько строк кода в комментарии. Таким образом, вы можете (временно) исключить часть кода из компиляции.
Чтобы закомментировать одну строку кода, используйте однострочные символы комментирования «//» .
Не закомментировано :
Закомментировано :
Чтобы закомментировать блок кода, используйте однострочные символы комментирования // на каждой строке или символы многострочного комментария » /* */ » .
Не закомментировано :
Закомментировано символами однострочного комментария :
Закомментировано символами многострочного комментария :
Есть несколько причин, почему следует использовать «закомментирование» :
Причина №1 : Вы работаете над новой частью кода, которая пока что не рабочая, но вам нужно запустить программу. Компилятор не позволит выполнить программу, если в ней будут ошибки. Временное отделение нерабочего кода от рабочего комментированием позволит вам запустить программу. Когда код будет рабочий, то вы сможете его легко раскомментировать и продолжить работу.
Причина №2 : Вы написали код, который компилируется, но работает не так, как нужно и сейчас у вас нет времени с этим возиться. Закомментируйте код, а затем, когда будет время, исправьте ошибки.
Причина №3 : Поиск корня ошибки. Если вас не устраивают результаты работы программы (или вообще происходит сбой), полезно будет поочерёдно «отключать» части вашего кода, чтобы понять какие из них рабочие, а какие — создают проблемы. Если вы закомментируете одну или несколько строчек кода и программа начнет корректно работать (или пропадут сбои), шансы того, что последнее, что вы закомментировали, является ошибкой — очень велики. После этого вы сможете разобраться с тем, почему же этот код не работает так, как нужно.
Причина №4 : Тестирование нового кода. Вместо удаления старого кода, вы можете его закомментировать и оставить для справки, пока не будете уверены в том, что ваш новый код работает так, как нужно. Как только вы будете уверены в новом коде, то сможете без проблем удалить старые фрагменты кода. Если же новый код у вас будет работать не так, как нужно, то вы сможете его удалить и откатиться к старому коду.
Примечание: Во всех следующих уроках я буду использовать комментарии в иллюстративных целях. Внимательные читатели смогут заметить, что по вышеуказанным стандартам большинство из этих комментариев будут плохими. Но помните, что использовать я их буду в образовательных целях, а не для демонстрации хороших примеров.
Источник: dzen.ru