Комментирование в C: зачем ставить комментарии в коде своей программы
Комментарии в С — это специальные пояснительные строки, которые помогают зафиксировать, а потом через время понять смысл написанного кода. Комментарии рассчитаны для людей и никак не воспринимаются компилятором или интерпретатором.
Комментарии в С могут писаться в одну или несколько строк. В зависимости от этого синтаксис комментариев будет отличаться, об этом чуть ниже.
Комментарии в С
Для чего нужны комментарии в С?
Комментарии в С и в других языках программирования нужны:
Чтобы не запутаться при разработке собственных библиотек, функций, методов и переменных.
Чтобы описать сложные алгоритмы или формулы. Если ваша программа завязана на сложных математических расчетах, то комментарии будут незаменимы.
Как оформить комментарии в С?
Однострочные комментарии в С обозначаются двумя наклонными линиями «//» только в начале самого комментария.
Многострочные комментарии в С обозначаются с двух сторон, отмечая начало и конец комментария. В качестве обозначения таких комментариев применяют сочетание наклонной линии и «звездочки». Многострочный комментарий будет выглядеть так: « /*многострочные комментарии в С*/ ».
По каким правилам пишутся комментарии в С?
Изначально можно подумать, что раз комментарии в С не читаются интерпретаторами и компиляторами, то можно их писать где хочешь и сколько хочешь, просто правильно оформляя. Так никто не запрещает поступать, но есть общепринятые рекомендации по написани ю комментариев. Лучше и х придерживаться, чтобы ваш код был не только эффективным, но и правильно оформленным.
Рекомендации о том, как писать комментарии в С:
Место написания. Комментарии в С рекомендуется писать справа от строки, к которой они относятся, если комментарий короткий ; и сверху над кодом, к которому они относятся, если комментарий многострочный.
Область комментирования. Комментируется не все подряд, а только основные и значимые части кода: функция, модуль, константа, глобальная переменная, интерфейс, класс и др.
Размер комментария. Комментарии в С не должны выглядеть как целые поэмы. Нужно писать максимально коротко и только по делу. Любой комментарий, который не несет смысла, не должен присутствовать в коде.
Кстати, все комментарии в С по смысловой нагрузке можно разделить на 2 группы:
Для пояснения. Сюда включают все комментарии в С, которые разъясняют логику поведения кода, функции, алгоритма и т. д. Наличие комментариев такого рода регламентируются самим разработчиком. Именно они обеспечивают дальнейшее удобство взаимодействия с кодом и пояснение его составляющих.
Когда нужны комментарии в С, а когда — нет?
Однако при этом не стоит просто нагружать документ ненужными комментариями. То есть не т необходимости комментировать то, что и так очевидно. Пример того, как делать не надо:
Для переменной age указываем значение 45
То есть тут и так все понятно, поэтому не нужно засорять код такими комментариями. Изначально важно стремиться к тому, чтобы писать код, не требующий подробного комментирования. А если комментарий и пишется, то только по делу.
Заключение
Запомните! Лучше писать простой и понятный код, чем писать непонятный и запутанный, но с большим количеством комментариев.
Мы будем очень благодарны
если под понравившемся материалом Вы нажмёте одну из кнопок социальных сетей и поделитесь с друзьями.
Как комментировать исходный программный код
Программисты не всегда правильно понимают, как комментировать код. А новички и вовсе не знают об этой функции. Многие пользователи сталкивались с комментированием, но могли не знать, что это такое. Рассмотрим основные моменты этого процесса.
Что такое комментирование
Это пояснение созданного программного кода, которое умещается в нескольких строках текста. Комментарии делают не для машины, а для программистов. Компиляторы и интерпретаторы не обращают внимания на комментарии. Они никак не влияют на работоспособность кода.
Ниже показан пример комментирования на языке C++. В этом случае комментарий начинается после 2 слешей (//):
Как помогает комментирование
Разберемся, как комментирование помогает программисту в его работе:
Пример описания процесса в комментировании:
Комментарии понадобятся не только в англоязычных языках программирования, но и в языках с русскими символами (например, 1С или ДРАКОН). Человеку может показаться, что в таких языках и так все понятно и не нужно ничего комментировать. Это ошибочное мнение. Код на русском языке так же забывается.
Оформление комментария в коде
Однострочный комментарий выделяется одиночным символом в начале и в конце строки. Многострочный имеет разные размеры, но поддерживается не всеми языками. Отмечается символами в начале и конце: /* и */.
Чтобы выделить комментарии, используют определенные символы. Они разнятся в зависимости от языка программирования:
Правила комментирования
Программисты во время комментирования придерживаются некоторых правил. Они упрощают работу и делают процесс понятнее.
Рассмотрим подробнее эти правила:
Комментирование функций и библиотек
В комментариях к ним пишут:
В качестве примера рассмотрим комментарий в заголовке библиотеки Lodash:
В заголовочном комментарии к функциям пишутся следующие данные:
В качестве примера снова Lodash:
Избегаем бессмысленных комментариев. Пример неправильного описания процедуры на 1С:
Автоматизация комментирования
Подобное предусмотрено с помощью IDE. Для этого используются теги-дескрипторы. Они начинаются с символа @.
Самые часто используемые теги-дескрипторы:
Подобные комментарии автоматически собирают программную документацию. Для сбора применяются генераторы документации. К примеру, для Java используют генератор javadoc.
Работает генератор документации достаточно просто. Он анализирует файл с исходным кодом и выискивает в нем имена:
Далее генератор связывает данные из комментариев с тегами. Затем создается документация, хранящаяся в разных текстовых форматах (HTML, PDF и других).
Во время создания фреймворков и библиотек формируются документы для API. Их нужно обновлять, т.к. они устаревают.
Комментирование сложного кода и рефакторинг
Большой и сложный код обязательно должен иметь поясняющие комментарии.
Код можно упростить: разбить его на функции, простые циклы и уменьшить все элементы. Через комментирование вы можете дать имена разбитым частям — они расскажут о значении каждого элемента.
К примеру, существует метод, сравнивающий числа a и b. Если a > b, метод возвращает true, а если a
Комментарии (программирование)
Коммента́рии — пояснения к исходному тексту программы, находящиеся непосредственно внутри комментируемого кода. Синтаксис комментариев определяется языком программирования. С точки зрения компилятора или интерпретатора, комментарии — часть текста программы, не влияющая на её семантику. Комментарии не оказывают никакого влияния на результат компиляции программы или её интерпретацию. Помимо исходных текстов программ, комментарии также применяются в языках разметки и языках описания.
Содержание
Назначение комментариев
Большинство специалистов сходятся во мнении, что комментарии должны объяснять намерения программиста, а не код; то, что можно выразить на языке программирования, не должно выноситься в комментарии — в частности, надо использовать говорящие названия переменных, функций, классов, методов и пр., разбивать программу на лёгкие для понимания части, стремиться к тому, чтобы структура классов и структура баз данных были максимально понятными и прозрачными и т. д. Есть даже мнение (его придерживаются в экстремальном программировании и некоторых других гибких методологиях программирования), что если для понимания программы требуются комментарии — значит, она плохо написана.
Концепция грамотного программирования настаивает на включение в текст программы настолько подробных и продуманных комментариев, чтобы она стала исходным текстом не только для исполняемого кода, но и для сопроводительной документации.
Комментарии часто используются для временного отключения части кода. В языках C и C++, некоторые рекомендуют использовать с той же целью директивы препроцессора ( #if 0 … #endif ).
Однострочные и многострочные комментарии
С точки зрения синтаксиса, существуют два вида комментариев. Многострочный комментарий может иметь любую длину, он отмечается специальными символами в начале и конце (например, /* */ ). Некоторые языки позволяют вложение многострочных комментариев, другие — нет.
Однострочный комментарий отмечается специальным символом в начале (например, // ) и продолжается до конца строки. Обычно допускается вложение однострочных комментариев в другие, как одно- так и многострочные комментарии. Способы записи можно чередовать, с точки зрения семантики они одинаковы.
Аннотации
Другой вид комментариев — аннотации — применяется в набросках доказательств правильности программ. Такие комментарии описывают состояние компьютера, когда программа в процессе выполнения достигнет точки, где расположен комментарий. Программа, снабжённая комментариями-аннотациями, называется аннотированной программой.
Автоматическая генерация документации
Документирующие комментарии как правило оформляются как многострочные комментарии в стиле языка Си. В каждом случае комментарий должен находиться перед документируемым элементом. Первым символом в комментарии (и вначале строк комментария) должен быть *. Блоки разделяются пустыми строками.
В некоторых средах программирования (например, Eclipse, NetBeans, Python, Visual Studio) документирующие комментарии используются в качестве интерактивной подсказки по интерфейсу классов и функций.
Трансляция программ
Во время трансляции комментарии распознаются на стадии лексического анализа (и, соответственно, считаются лексемами). Распознавание на стадии препроцессирования накладно и даже чревато ошибками; включение комментариев в синтаксические диаграммы практически невозможно.
В различных языках и средах программирования
Специальные комментарии
Комментарии должны игнорироваться транслятором, но на практике это не всегда так. Некоторые специальные команды транслятору, сильно зависящие от реализации языка программирования, часто оформляются как комментарии.
Например в диалекте Турбо Паскаль псевдокомментарии <$I->и <$I+>используются для отключения и включения стандартного контроля ошибок ввода-вывода. Похожие специальные комментарии используются в языке разметки HTML для указания типа SGML-документа, «экранирования» таблиц стилей и сценариев на языках JavaScript и VBScript:
Некоторые комментарии программисты используют в ходе своей работы. Подобные комментарии особенно полезны, когда над одним кодом работает несколько разработчиков. Так, комментарием TODO обычно помечают участок кода, который программист оставляет незавершённым, чтобы вернуться к нему позже. Комментарий FIXME помечает обнаруженную ошибку, которую решают исправить позже. Комментарий XXX обозначает найденную критическую ошибку, без исправления которой нельзя продолжать дальнейшую работу.
Хороший, плохой, злой комментарий
Зачем нужны комментарии, правда ли, что хороший код можно прочитать без них и как перфекционизм замедляет разработку в 4 раза. Новичкам, командам, профи.
«Хороший, плохой, злой», 1966 г.
Интуитивное знакомство
с комментариями как и в любых отношениях создаёт скрытые проблемы. Со stackoverflow или от своего творческого начала мы неосознанно формируем манеру комментирования. Кто-то излишне подробную, кто-то с юморком, а кто-то вообще пишет «без комментариев» и через пол года даже не пытается понять, как работает его код.
П.С. Если ты тот человек, который узнал о комментариях в коде из книги, дай знак) Если тебе сразу нужны ответы – они в конце.
В маленькой веб-студии или в соло-проектах мы сами себе указ и можем писать там хоть анекдоты, вопрос о «технологии» комментирования возникает при переходе к командной разработке, особенно если есть сопровождение продукта. Чтение чужого кода становится не наказанием, а ежедневным занятием. Но сначала и наказанием, пока не наступает момент Х, момент обратиться за знанием.
Особенно важно, когда этот момент наступает для целой команды или даже отдела. Ни в коем случае нельзя его упускать – это шанс дружно изменить ситуацию к лучшему, другой момент такого «вскипания» в маленьком проекте может и не наступить, т.к. код копится, как и отчаяние.
Даже в сформированных командах с регламентами и организацией труда, комментирование зачастую интуитивный процесс, чем сознательная часть разработки.
Совершенный код –
это перевод названия книги*. Из 950 страниц осмысленного текста, популярность обрела одна фраза: «хороший код является самодокументированным«. А к ней пояснения в виде: «хорошему коду не нужны комментарии», «называй переменные и методы понятно, тогда комментарии не нужны».
Круто быть столь категоричным, а главное – просто. Но к чему это приводит? Часть превращает комментарии в искусство, стремится к идеалу, размышляет по 20 минут над названиями. Другая часть – формирует чек-листы, правила оформления, требует соблюдения шаблонов. И то, и другое полезно, вот только они забывают о «смысле жизни» комментариев.
Из возможных 20% времени программирования, которые есть у соло-разработчика, в команде остаётся всего 5.
Творчество и точность – это очень красиво, но когда помогает достичь цель. Понятные имена, комментарии и другие инструменты нужны чтобы снизить неопределенность.
В примере выше, 20% времени уделяется программированию и 80% – решению того, что и как программировать, изучению контекста, ТЗ. Это бОльшая часть работы по умолчанию. И чем больше проект, тем ближе к 100% можно «страдать» / «ничего не делать» (нужное подчеркнуть). Чтение даже идеального кода == не программирование.
Происходит ситуация, как в поиске по файлам в Win – человек перебирает все файлы, строчки, операции, чтобы найти «то самое» место, где его ждет работа, вместо того, чтобы пробежаться по индексам и через минуту уже выдать новую строчку кода. Вторая функция комментариев – обеспечить быструю навигацию.
Всё остальное – лишь форма. Помните о смысле, тогда она будет руслом, а не плотиной из ограничений и бюрократии.
*Code Complete, Стив Макконнелл, 1993. Для сохранения смысла точнее будет перевести как «Завершение кода» или «Завершенный код». Комментарии – то, что делает код завершенным, готовым к «эксплуатированию» пользователями, разработчиками, а также обеспечивает комфорт его доработок.
Ответы
П.С. По оформлению кода и комментариев есть много руководств, вместо очередного, здесь – тезисы для размышлений.
Существуют разные варианты «использования» кода и комментарии для них отличаются.
Подключение по типу «чёрный ящик» – пользователя интересует только что на входе/выходе. Обычно в виде шапки в файле класса и около методов. Хорошо указывать в шапке дату актуализации, перечень методов (содержание). Идеальное использование: за минуту прочитал и пользуешься.
Открытая библиотека – возможны большие комментарии с описанием принципов, данных, нюансов конкретных решений в коде. Пол часика почитал, пользуешься, в процессе изучаешь дальше.
Разработка – комментарии в коде, короткие, описывающие этапы, группы/блоки операций, а так же комментарии вида TODO (сделать), FIX (исправить) и т.д. Они не дублируют код, а иллюстрируют, как краткое содержание параграфов. В идеале: посмотрел шапку, пробежался по описаниям и нашел нужное место за пару минут – работаешь.
Неопределенность и навигация. Можно прочитать 10 000 строк идеального кода, понять его и исправить 3 строчки. Хорошие комментарии – те, что позволят сделать это «сразу», а не к обеду. Плюсом будет документирование архитектуры (хотя бы), но это другая история.
Красота – единообразие не только красиво, но и понятно. Привычное быстрее воспринимается. Определите удобные для себя правила оформления в команде.
Шаблоны – упрощают жизнь, но без фанатизма, у функций бывают необязательные параметры.
На этом у меня всё, успехов!
П.С. Буду рад дополнить статью идеями из. комментариев.
Зачем комментировать исходный код и как это делать правильно
Как не забыть о том, что вы имели ввиду полгода назад, когда писали этот программный код? Разбираемся с использованием комментариев.
Комментарии — поясняющие строки в программном коде, которые позволяют понять смысл написанного. Они пишутся для людей, но игнорируются компиляторами и интерпретаторами.
Знакомый, наверно, каждому пример со словами на русском или английском языке после двух слешей — так обычно выглядят комментарии:
Программист, консультант, специалист по документированию. Легко и доступно рассказывает о сложных вещах в программировании и дизайне.
Чем комментарии могут помочь программисту
Комментарии, в зависимости от ситуации, делают сразу несколько полезных вещей:
Как комментарии оформляют в коде
Комментарии бывают совсем короткими, длиной не более строки, и большими, многострочными.
Однострочные выделяют одиночным символом в начале и продолжают до конца строки, а многострочные могут иметь любую длину, но поддерживаются не всеми языками. Их отмечают специальными символами в начале и конце текста, например, /* и */.
Для выделения комментариев в коде используют разные символы:
Правила, которых принято придерживаться
У разработчиков принято использовать при комментировании несколько простых правил. Так легче работать — больше пользы и не нужно плодить лишние строки кода.
1. Комментарии помещаются прямо над кодом, к которому они относятся. Так проще понять, о чём речь, не вникая в содержание каждой строчки. Совсем короткие пояснения можно писать справа.
2. Комментируют все основные элементы кода: модули, функции, константы, глобальные переменные, интерфейсы, классы и их составные элементы (методы, свойства, константы).
3. Пишут коротко и по делу. Комментарии без смысловой нагрузки страшно раздражают. Не нужно писать комментарии типа «это гениальный код», «таблица1», «! №; %:? *» и подобные.
4. Нельзя, чтобы комментарии оскорбляли кого-то или содержали слова, которые не поймёт технарь. В поддержку движения Black Lives Matter Twitter в своем коде решил не использовать слова slave, master и blacklist. Кто-то из россиян, возможно, улыбнётся, но стандарт есть стандарт.
Документирующие и поясняющие комментарии
В зависимости от того, для чего нужны комментарии, их условно делят на два вида:
Пример на языке Java:
Из такого комментария сразу ясно, что делает программа. Не нужно вникать в исходный текст и изучать техническую документацию. Это особенно важно, если вы работаете в команде и хотите сэкономить время коллег.
Комментарии-описания иногда мешают разработчикам и отвлекают внимание от основного кода. Поэтому в большинстве современных редакторов есть возможность свернуть или скрыть комментарии.
Как комментируют функции и библиотеки
В комментариях к файлам и библиотекам указывают информацию о проекте, назначении модуля, заносят в них имя разработчика, номер версии продукта и лицензию на программное обеспечение.
Например, документирующий комментарий из заголовка библиотеки Lodash для JavaScript выглядит так:
Кроме этого, в заголовочных комментариях к функциям указывают стандартный набор сведений:
Пример из той же библиотеки Lodash:
Главное здесь — избегать бессмысленных комментариев. Вот пример плохого описания процедуры на языке 1С:
К прикладным процедурам, функциям и классам делайте информативные и понятные заголовки с описанием всех входных и выходных параметров.
Как автоматизировать создание комментариев
В различных IDE есть возможность автоматизировать создание комментариев. Это делается с использованием тегов — дескрипторов, которые начинаются с символа @. Вот самые популярные:
Из таких комментариев автоматически формируется документация программы. Для этого используют генераторы документации, например, javadoc для языка Java, phpDocumentor для PHP, doxygen для C и C++, Epydoc для Pithon и другие.
Принцип работы прост. Генератор обрабатывает файл с исходным текстом, находит там имена классов, их членов, свойств, методов, процедур и функций, а затем связывает их с данными из наших комментариев с тегами. Из этой информации формируется документация в формате HTML, PDF, RTF или других.
При разработке библиотек и фреймворков обычно создается документация для API. Со временем она устаревает — в неё не успевают или просто забывают вносить изменения.
Если данные об изменениях в коде отражены в комментариях, с помощью генераторов документацию можно регулярно обновлять.
Когда нужны пояснения в коде, а когда — нет
Бывает, что одних документирующих комментариев недостаточно и нужно добавить пояснения внутри процедур или функций. Такие комментарии облегчают понимание кода — рассказывают, почему автор программы сделал что-то так, а не иначе.
Но иногда эти пояснения только ухудшают наглядность кода, бывают бессмысленны и даже вредны. Например, совершенно не нужны комментарии, просто пересказывающие действия программы:
Если вы вставили промежуточные комментарии для отладки или объяснения результатов, после окончания работы их нужно убрать. Иначе они будут захламлять код.
Например, функция вычисляет окончательную сумму, прибавляя проценты к основной. Для проверки программист вывел на экран промежуточный результат, а после закомментировал ненужный фрагмент.
После отладки их лучше удалить, оставив строки:
Простой код, без многочисленных циклов, ветвлений и переходов, пишут и структурируют так, чтобы никаких дополнительных пояснений к нему не требовалось.
Но бывают исключения. Допустим, разработчик попробовал несколько вариантов решения и выбрал один, не самый очевидный. Потом забыл ход своих мыслей, открыл код и решил использовать «более правильный и оптимальный вариант». И тут он понимает, что новое решение хуже старого; более того, раньше он уже это пробовал делать. Приходится откатывать всё назад. Чтобы не попасть в такую ситуацию, пишите поясняющие комментарии.
Пример на языке JavaScript:
Здесь и сам метод Number.isFinite (), и глобальная функция isFinite () проверяют, является ли параметр value конечным числом (то есть не ± ∞). Но если value = null, то isFinite (value) возвращает true, а Number.isFinite (value) возвращает false. Поэтому Number.isFinite (value) нельзя менять на isFinite (value).
Обязательно комментируйте код, если в нём есть какие-то тонкости и неочевидные вещи. Например:
Это неудачный комментарий: непонятно, зачем количество умножать на 2.
Правильно будет так:
В любом случае, старайтесь писать поясняющие комментарии как можно реже.
Комментарии в сложном коде и рефакторинг
В сложной и запутанной программе не обойтись без поясняющих комментариев. Но иногда лучше упростить сам код: разбить на отдельные функции, уменьшить размеры элементов, упростить циклы и так далее. А самим функциям, константам и переменным дать «говорящие» имена, объясняющие их назначение.
Например, есть метод, который сравнивает числа a и b. Если a > b, он возвращает true, a если a
Весь этот громоздкий кусок кода можно значительно упростить, просто убрав блок if-else:
Теперь метод выглядит намного проще и элегантнее, хотя его суть не изменилась. Подобные преобразования называются рефакторингом.
Рефакторинг меняет структуру кода, оставляя неизменной его суть. Он повышает читаемость кода и облегчает процесс его доработки. Рефакторинг не заменяет комментирование, но с ним комментариев нужно намного меньше.
Что в итоге
Комментарии — отличная штука. Они помогают команде разработчиков работать над общим проектом. А если программист один, позволят ему даже через много лет вспомнить ход своих мыслей. Но комментариев должно быть мало, иначе они превратятся во флуд.
Комментировать нужно основные элементы кода, неочевидные решения, сложные бизнес-процессы, тонкости решений и тому подобное. Не пишите комментарии, объясняющие, что и как делает процедура или функция, — это бессмысленно.
И помните, что комментарий — не панацея, он не спасёт плохой код, даже если сделает его понятнее. Сложные и запутанные фрагменты сокращайте и делайте рефакторинг, а комментируйте по минимуму.
Научиться использовать комментарии, верно документировать исходный код, писать его понятным для коллег и читабельным даже через много лет вы можете на наших курсах по программированию. Выбирайте любой и становитесь профессионалом.
Quality Assurance дословно означает «обеспечение качества» — специалисты отвечающие за функциональное тестирование программного обеспечения на этапе разработки.
Агоритмический язык, который разработан и используется в ПО для управления оборудованием «Буран», «Морской старт», «Фрегат», «Протон-М» и других космических программ РФ.
Встроенный язык программирования, который используется в семействе программ «1С: Предприятие». Является интерпретируемым языком высокого уровня.
Б иблиотека JavaScript, которая предоставляет вспомогательные функции для общих задач программирования с использованием парадигмы функционального программирования.
Интегрированная среда разработки, (Integrated development environment) — комплекс программных средств, используемый программистами для разработки программного обеспечения.