Как комментировать в c

В С все комментарии начинаются с пары символов /* и заканчиваются парой */. Между слэшем и звездочкой не должно быть пробелов. Компилятор игнорирует любой текст между данными парами символов. Например, следующая программа выводит на экран только hello:

#include
int main(void)
printf(«hello»);
/* printf(«there»); */
return 0;
>

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

х = 10 + /* сложение чисел */ 5;
в то время как
swi//* не работает */tch(c) < . . .

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

Комментарии не могут быть вложенными, т.е. один комментарий не может содержать другой комментарий. Например, следующий фрагмент кода вызовет ошибку при компиляции:

/* внешний комментарий
х = у / а;
/* внутренний комментарий вызывает ошибку */
*/

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

ЗАМЕТКА: С++ полностью поддерживает С-стиль комментариев. Тем не менее он также позволяет определять однострочные комментарии. Однострочный комментарий начинается с // и заканчивается в конце строки.

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

Как-то раз сидел в аудитории с ноутом около розетки, а в это время на соседней парте принимался зачет по программированию. Я не сильно вникал в суть вопросов на которые общались студент и преподаватель, назовем его Иван Ивановичем. Разговор был довольно спокойный и тихий, но у меня получилось выхватить часть. Преподаватель говорил о комментариях (видимо сдавалась программа, в которой не было ни строчки комментариев). Меня этот момент заинтересовал и я начал прислушиваться. Было замечено, что мне тоже интересно, преподаватель начал импровизированную лекцию. Ниже представлен тот небольшой кусок знаний который я тогда вынес с этой 5ти минутной лекции.

Хочется сразу предупредить, что для многих описанное здесь — очевидные вещи, однако, новичкам в коллективном программировании (когда над кодом работают 2 и более программиста) и студентам будет полезно. Кроме того, все изложенные ниже советы имеют альтернативу и могут быть использованы лишь частично.

Почему я приписал сюда студентов? Они же, казалось бы, одни работают над программой на зачет! Препод, когда принимает программу, справедливо считается вторым разработчиком, который в идеале без помощи студента должен понять, что там написано и как оно работает.

Как писать код сразу с комментариями

По сути говоря, на той лекции принцип TDD (Test-driven development, разработка через тестирование) был перенесен на уровень ниже. Не помню как это звучало в оригинале, но по сути «Опиши комментариями структуру кода». На примере (сильно утрированном, почему — ниже) кода программы, складывающей два числа, этот принцип будет выглядеть так:

int main() < // Принять от пользователя два числа // Завести переменную для результата сложения // Вернуть результат сложения return 0; >

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

. int main() < double a,b; // Принять от пользователя два числа cin>>a; cin>>b; //Завести переменную для результата сложения double sum = a+b; // Вернуть результат сложения cout

Как упоминалось выше, данный принцип представляет собой модифицированный принцип, хорошо зарекомендовавшего себя TDD. Тут следует понимать, что отступление от комментариев, в отличии от отступления от логики тестов, не приведет к тяжелым последствиям, ну разве что придется комментарии переписывать

Теперь представим «чисто гипотетическую» ситуацию, когда уже имеется код в 200 000 строк, написанный ~~гениальным программистом~~ криворуким индусом и не содержит ни строчки комментария. Однако вам необходимо, мало того что ~~убить этого программиста~~ понять этот код, но и сопровождать его в дальнейшем. Вы даже разобрались в этом коде, и будучи приличным человеком, решили дополнить код комментариями для, так сказать, будущих поколений. Но возникает вопрос: как?

Как комментировать уже существующий код

Ответ на этот вопрос довольно прост: комментируем сущности от родителя к потомку: класс -> метод -> код внутри метода (если необходимо).

Совсем уж очевидные вещи. Комментарии вида // инициализируем счетчик бесят больше чем их отсутствие
Непонятный код дополнять комментарием типа // ничего не понял

Напоследок

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

Комментарии в C#

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

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

В C# есть 3 типа комментариев:

однострочные комментарии ( // );
многострочные комментарии ( /* */ );
комментарии XML ( /// ).

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

Однострочные комментарии в C# начинаются с двух слешей: // . Компилятор игнорирует все слова, начиная с // и заканчивая концом строки.

int a = 5 + 7; // Прибавляем 7 к 5

«Прибавляем 7 к 5» — это комментарий.

Пример 1. Используем однострочный комментарий

// Программа «Привет, мир!» using System; namespace HelloWorld < class Program < public static void Main(string[] args) // Выполнение начинается с метода Main < // Выводит на экран сообщение «Привет, мир!» Console.WriteLine("Привет, мир!"); >> >

В программе выше 3 однострочных комментария:

Программа «Привет, мир!» ;
Выполнение начинается с метода Main ;
Выводит на экран сообщение «Привет, мир!» .

Однострочные комментарии можно записывать в отдельной строке или в одной строке с кодом. Лучше — в отдельной строке, таковы рекомендации по написанию кода на C#.

Пример 2. Используем многострочные комментарии

/* Это программа «Привет, мир!» на C#. Она выводит на экран сообщение «Привет, мир!». */ using System; namespace HelloWorld < class Program < public static void Main(string[] args) < /* Выводит на экран сообщение «Привет, мир!» */ Console.WriteLine("Привет, мир!"); >> >

В программе выше 2 многострочных комментария:

/* Это программа «Привет, мир!» на C#. Она выводит на экран сообщение «Привет, мир!». */

/* Выводит на экран сообщение «Привет, мир!» */

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

Комментарии документации XML

Комментарии к документации XML — это особая фича C#. Они начинаются с тройной косой черты `///` и используются для описания фрагмента кода с помощью XML-тегов. Из таких комментариев позже создают отдельные файлы документации XML.

О XML можно почитать в этой статье.

/// /// Это тоже программа «Привет, мир!» ///
 using System; namespace HelloWorld < class Program < public static void Main(string[] args) < Console.WriteLine("Привет, мир!"); >> >

Вот XML-комментарий в программе выше:

/// /// Это тоже программа «Привет, мир!» ///

Сгенерированная XML-документация (файл с расширением .xml) будет выглядеть вот так:

   HelloWorld

Подробнее о XML-документации можно узнать в руководстве от Microsoft.

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

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

Например, здесь комментарий лишний:

// Выводит Hello World Console.WriteLine ("Привет, мир!");

И без него очевидно, что напечатается сообщение «Привет, мир!». В таких случаях комментариев лучше избегать.

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

СodeСhick.io — простой и эффективный способ изучения программирования.

C#: Комментарии

Практически все языки программирования позволяют оставлять в коде комментарии. Они никак не используются кодом и нужны исключительно для людей: чтобы программист оставлял пометки для себя и для других программистов. Комментарии в 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

Документирующие комментарии для каждой строчки используют /// .

Документирующие комментарии, являясь, по сути, подвидом однострочных, несут дополнительную функцию – добавляют подсказки к коду для внешних пользователей нашего кода. Мы поговорим о них позже – когда разберём классы и методы.

Задание

Создайте однострочный комментарий с текстом: You know nothing, Jon Snow!.

Упражнение не проходит проверку — что делать? ��

Если вы зашли в тупик, то самое время задать вопрос в «Обсуждениях». Как правильно задать вопрос:

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

В моей среде код работает, а здесь нет ��

Тесты устроены таким образом, что они проверяют решение разными способами и на разных данных. Часто решение работает с одними входными данными, но не работает с другими. Чтобы разобраться с этим моментом, изучите вкладку «Тесты» и внимательно посмотрите на вывод ошибок, в котором есть подсказки.

Мой код отличается от решения учителя ��

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

В редких случаях бывает, что решение подогнано под тесты, но это видно сразу.

Прочитал урок — ничего не понятно ��

Создавать обучающие материалы, понятные для всех без исключения, довольно сложно. Мы очень стараемся, но всегда есть что улучшать. Если вы встретили материал, который вам непонятен, опишите проблему в «Обсуждениях». Идеально, если вы сформулируете непонятные моменты в виде вопросов. Обычно нам нужно несколько дней для внесения правок.

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