C и C# – два распространенных языка программирования, которые помогают создавать различное программное обеспечение. Они имеют схожие черты и компоненты.
В коде в C и C# могут встречаться комментарии. Они в обоих упомянутых языках разработки поддерживаются одинаково. Предложенная далее информация, а также правила оформления и области применения актуальны для рассматриваемых ЯП в равной степени. Статья ориентирована преимущественно на разработчиков-новичков, которые ранее не имели ничего общего с разработкой и оформлением кода.
Определение
Комментирование в программе – распространенный прием, помогающий в большинстве языков программирования. С его помощью оформляют отдельные «модули» в будущем программном обеспечении. Они будут игнорироваться компилятором в исходном коде/программе. Это значить, что комментирование требуется «для пользователя/разработчика».
Комментарии в C ориентированы на тех, кто не умеет работать с языком и его конструкциями. Это своеобразные примечания (подсказки). С их помощью разработчик сделает исходный код Си более читабельным и чистым.
Комментирование при грамотном подходе – элементарный способ документирования. Оно может быть использовано в самых разных ситуациях.
Области применения
В программе разработчики комментируют то, что считают нужным. По смысловой нагрузке комментарии в коде разделяются на две категории:
- Для пояснений. Они расшифровывают поведение кода, функций, алгоритмов и иных компонентов исходного приложения. Способствуют более удобному взаимодействию с кодов и поясняют его элементы.
- Для документирования. Обязательная группа комментариев. Они расположены в самом начале исходного файла. Включают в себя сведения о разработчике, программе, библиотеках и иных параметрах, оказывающих влияние на код. Это своеобразное предисловие, помогающее сформировать общее представление о контенте.
Комментарий в C и C#, а также иных языках разработки может использоваться для самых разных целей:
- Помочь разобраться в том, что написано в исходном документе. Здесь ситуация может быть абсолютно разной – другой разработчик пытается понять, что написано, или первоначальный создатель решил вернуться к проекту спустя долгое время.
- Правильный и грамотно написанный программистом комментарий поможет разобраться при создании собственных методов, библиотек, функций и переменных.
- Тестирование программы. При обнаружении ошибок комментарии помогают быстрее найти «проблемное» место в коде.
- Описание сложных алгоритмов и формул. Эта область применения в основном актуальная для программных продуктов, требующих сложных математических расчетов.
Рекомендуется не комментировать «все, что написано». Рассматриваемый процесс может создать как ясность, так и визуально испортить исходное программное обеспечение.
Разновидности и классификация
C имеет несколько типов комментариев. Каждый из них предусматривает свои собственные правила оформления и другие нюансы:
- Однострочный. Название говорит само за себя. Это – элементарный комментарий, который в коде записывается в одну строку. Обычно выступает некой «заметкой».
- Многострочный. Закомментировать в C и других языках предлагается не одну, а несколько строк. Многострочный комментарий используется в документации и развернутом описании блока кода/функции.
В C# дополнительно поддерживаются XML-комментарии. В них используются описания фрагментов исходного кода при помощи XML-тегов. Из соответствующих компонентов может быть создан отдельный файл документации XML.
Правила оформления
Правильный исходный код программы, который грамотно закомментирован, будет понятным и «прозрачным». Разработчикам рекомендуется придерживаться нескольких простых правил, которые помогут не нагружать приложение «заметками»:
- Место написания «подсказки». Комментарии пишутся справа от строки, к которой они относятся или сверху над кодом. В первом случае речь идет об однострочном комментарии, во втором – о многострочном.
- Область комментирования. Рекомендуется оставлять «заметки» только для значимых (или сложных/непонятных) элементов: функции, модули, константы, глобальные переменные, классы, интерфейсы и так далее.
- Размер комментария. Если используется однострочный комментарий в коде, с его «объемом» все ясно. В противном случае не рекомендуется составлять целые «поэмы». Многострочная «подсказка» должна быть лаконичной и максимально простой, короткой.
Строгих правил комментирования нет, но предложенные вниманию правила являются негласными стандартами.
В зависимости от типа комментария в коде разработчикам приходится использовать различные символьные записи для их внедрения. Чтобы компилятор в C и C# понимал написанное как «заметку», необходимо:
- в самом начале поставить два слеша (//) – для однострочного комментирования;
- многострочный комментарий начинается с /* и заканчивается */;
- три слеша (///) используются в C# для XML-комментариев.
Аналогичные правила комментирования используют другие языки программирования– Java, C++, JavaScript и так далее.
Наглядные примеры
Чтобы было ясно, как выглядит многострочный комментарий C или C#, а также однострочная «подсказка», рекомендуется рассмотреть несколько наглядных примеров. Они просто продемонстрируют общую форму представления «заметок для пользователей» в исходных кодах.
Так выглядит однострочный комментарий:
В приведенном фрагменте 3 соответствующих компонента. Они начинаются с «//». В случае с многострочным комментированием, ситуация будет выглядеть так:
Здесь две «подсказки» – перед using System и Console.Writeline. А вот – правильный XML-комментарий в коде:
Здесь он будет занимать 3 строки: <summary>, «Это тоже программа «Привет, мир!»» и «</summary>».
P. S. Интересует разработка? Обратите внимание на курс «Программист C». Также в Otus доступно множество других современных курсов.
