Комментирование в C: зачем ставить комментарии в коде своей программы

Комментарии в С — это специальные пояснительные строки, которые помогают зафиксировать, а потом через время понять смысл написанного кода. Комментарии рассчитаны для людей и никак не воспринимаются компилятором или интерпретатором.

Комментарии в С могут писаться в одну или несколько строк. В зависимости от этого синтаксис комментариев будет отличаться, об этом чуть ниже.

 

Комментарии в С

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

 

Для чего нужны комментарии в С?

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

Комментарии в С и в других языках программирования нужны:

1. Чтобы помочь в случае чего разобраться с написанным кодом. Ситуации могут быть разные: может, вы вернетесь к своему коду через год, и, если не будет комментариев, вы не поймете, что вы там писали; возможно, ваш код будут дорабатывать другие программисты, и комментарии помогут его быстрее понять.

2. Чтобы не запутаться при разработке собственных библиотек, функций, методов и переменных.

3. Для тестирования программы. В случае обнаружения ошибок комментарии в С помогут быстрее найти, откуда они происходят.

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

 

Как оформить комментарии в С?

Комментарии в С бывают разные: могут быть короткими и писаться в одну строку, а могут быть большими, чтобы подробно описать какой-то процесс, и поэтому они будут занимать несколько строк. От размера комментария зависит синтаксис, который можно использовать:

1. Однострочные комментарии в С обозначаются двумя наклонными линиями«//» только в начале самого комментария.

2. Многострочные комментарии в С обозначаются с двух сторон, отмечая начало и конец комментария. В качестве обозначения таких комментариев применяют сочетание наклонной линии и «звездочки». Многострочный комментарий будет выглядеть так: « /*многострочные комментарии в С*/ ».

Такой же способ обозначать комментарии применяют многие другие языки, например: С++, С#, Java, JavaScript и др.

 

По каким правилам пишутся комментарии в С?

Изначально можно подумать, что раз комментарии в С не читаются интерпретаторами и компиляторами, то можно их писать где хочешь и сколько хочешь, просто правильно оформляя. Так никто не запрещает поступать, но есть общепринятые рекомендации по написанию комментариев. Лучше их придерживаться, чтобы ваш код был не только эффективным, но и правильно оформленным.

Рекомендации о том, как писать комментарии в С:

1. Место написания. Комментарии в С рекомендуется писать справа от строки, к которой они относятся, если комментарий короткий; и сверху над кодом, к которому они относятся, если комментарий многострочный.

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

3. Размер комментария. Комментарии в С не должны выглядеть как целые поэмы. Нужно писать максимально коротко и только по делу. Любой комментарий, который не несет смысла, не должен присутствовать в коде.

    

Кстати, все комментарии в С по смысловой нагрузке можно разделить на 2 группы:

1. Для пояснения. Сюда включают все комментарии в С, которые разъясняют логику поведения кода, функции, алгоритма и т. д. Наличие комментариев такого рода регламентируются самим разработчиком. Именно они обеспечивают дальнейшее удобство взаимодействия с кодом и пояснение его составляющих.

2. Для документирования. Эта группа комментариев является обязательной. Такие комментарии в С располагаются в самом начале документа с кодом. Они несут в себе информацию о разработчике, о разрабатываемой программе, об используемых библиотеках и других параметрах, влияющих на работоспособность всего документа. Это своего рода предисловие ко всей программе, которое несет в себе основной посыл и общее представление о самом программном обеспечении. Иногда генерация подобных комментариев в С может происходить в автоматическом режиме, для этого применяют специальные генераторы. Для языка С таким генератором является «doxygen».

 

Когда нужны комментарии в С, а когда — нет?

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

Однако при этом не стоит просто нагружать документ ненужными комментариями. То есть нет необходимости комментировать то, что и так очевидно. Пример того, как делать не надо:

/*

Для переменной age указываем значение 45 

*/

int age=45

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

 

Заключение

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

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