Как оформляются комментарии в си программе

Как оформляются комментарии в си программе

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

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

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

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

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

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

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

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

© М.Л. Цымблер (mzym@susu.ru), Е.В. Аксенова (evaksen@mail.ru)

1.1 Подбор идентификаторов

1.1.1 Все идентификаторы должны выбираться из соображений читаемости и максимальной семантической нагрузки. Например:

Неудачными можно считать идентификаторы:

1.1.2 Идентификаторы рекомендуется подбирать из слов английского языка. Например:

Не очень удачными можно считать идентификаторы:

1.2 Написание идентификаторов

1.2.1 Идентификаторы констант и макроопределений рекомендуется писать заглавными буквами. Например:

1.2.2 Существуют разные подходы к написанию остальных идентификаторов. Например:

а) все буквы идентификатора пишутся маленькими, для разделения слов в идентификаторе используется символ "_"

б) в идентификаторах каждое слово, входящее в идентификатор, писать, начиная с большой буквы, остальные буквы — маленькие.

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

Принятого подхода нужно придерживаться во всем тексте программы.

2.1 Комментарии

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

2.2 Спецификация функции и прототипа

Для каждой пользовательской функции должна быть описана в виде комментария спецификация, содержащая следующую информацию:
а) назначение функции;
б) описание семантики параметров-значений (параметров, передаваемых по значению), если она неочевидна;
в) описание семантики параметров-переменных (параметров, передаваемых по ссылке), если она неочевидна.
г) описание семантики возвращаемого значения, если она неочевидна.
Например:

Читайте также:  Хорошая встраиваемая вытяжка для кухни отзывы

1) семантика параметров и возвращаемого значения очевидна:

2) семантика параметров очевидна, семантика возвращаемого значения неочевидна

3) семантика параметров и возвращаемого значения неочевидна

Замечание:
Если функция реализует какой-либо вычислительный метод (например: нахождение площади фигуры методом трапеций, поиск минимума функции методом Ньютона и т.п.), рекомендуется в теле функции поместить комментарий с кратким описанием метода, либо ссылку на источник, где описан метод.

Прототипы функций достаточно снабдить кратким комментарием назначения функции. Например:

2.3 Спецификация программного файла

Программный файл должен начинаться со спецификации в виде комментария, содержащего следующую информацию:
а) идентификация (имя) файла;
б) фамилия и копирайт автора;
в) дата написания файла;
г) версия языка программирования и замечания по компиляции программного файла в других версиях языка (если требуется);
д) назначение программного файла;
Например:

3.1 Лесенка

"Лесенка" должна отражать структурную вложенность языковых конструкций. Рекомендуется отступ не менее 2-х и не более 8-и пробелов. Принятого отступа нужно придерживаться во всем тексте программы. Правила написания конструкций (K&R стиль):

е) определение функции

3.2 Длина строк программного текста

Длина строк программы не должна превышать ширины экрана (80 символов). Инструкции длиннее 80 символов разбиваются на логические части, которые всегда значительно короче, чем изначальная строка, и распологаются со сдвигом вправо. То же самое относится к заголовкам функций с длинным списком аргументов и к длинным строковым константам. Например:

3.3 Прочие рекомендации

3.3.1 Рекомендуется при перечислении идентификаторов после запятой "," ставить один пробел " ". Например:

3.3.2 Рекомендуется всегда писать символ-разделитель операторов ";" (непосредственно после оператора). Например:

Обновл. 30 Ноя 2019 |

Комментарий — это строка (или несколько строк) текста, которая вставляется в исходный код для объяснения того, что делает этот код. В C++ есть два типа комментариев: однострочные и многострочные.

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

Однострочные комментарии — это комментарии, которые пишутся после символов // . Они размещаются в отдельных строках и всё, что находится после этих символов комментирования, игнорируется компилятором. Например:

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

Размещая комментарии справа от кода, мы затрудняем себе как чтение кода, так и чтение комментариев. Следовательно, однострочные комментарии лучше размещать над строками кода:

Читайте также:  Невозможно удалить каталог как удалить

Многострочные комментарии

Многострочные комментарии — это комментарии, которые пишутся между символами /* */ . Всё, что находится между звёздочками, игнорируется компилятором:

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

Многострочные комментарии не могут быть вложенными (т.е. одни комментарии внутри других):

Правило: Никогда не используйте вложенные комментарии.

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

Во-первых, на уровне библиотек/программ/функций комментарии отвечают на вопрос «ЧТО?»: «Что делают эти библиотеки/программы/функции?».

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

Во-вторых, внутри библиотек/программ/функций комментарии отвечают на вопрос «КАК?»: «Как код выполняет задание?».

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

В-третьих, на уровне стейтментов (однострочного кода) комментарии отвечают на вопрос «ПОЧЕМУ?»: «Почему код выполняет задание именно таким образом, а не другим?». Плохой комментарий на уровне стейтментов объясняет, что делает код. Если вы когда-нибудь писали код, который был настолько сложным, что нужен был комментарий, который бы объяснял, что он делает, то вам нужно было бы не писать комментарий, а переписывать целый код.

Примеры плохих и хороших однострочных комментариев:

(По коду это и так понятно)

(Теперь мы знаем, ПОЧЕМУ зрение у игрока равно нулю)

(Да, мы видим, что здесь подсчёт стоимости, но почему элементы делятся на 2?)

Программистам часто приходится принимать трудные решения по поводу того, каким способом решить проблему. А комментарии и существуют для того, чтобы напомнить себе (или объяснить другим) причину, почему вы написали код именно так, а не иначе.

И, наконец, комментарии нужно писать так, чтобы человек, который не имеет ни малейшего представления о том, что делает ваш код — смог в нём разобраться. Очень часто случаются ситуации, когда программист говорит: «Это же совершенно очевидно, что делает код! Я это точно не забуду». Угадайте, что случится через несколько недель или даже дней? Это не совершенно очевидно, и вы удивитесь, как скоро вы забудете, что делает ваш код. Вы (или кто-то другой) будете очень благодарны себе за то, что оставите комментарии, объясняя на человеческом языке что, как и почему делает ваш код. Читать отдельные строки кода — легко, понимать их логику и смысл — сложно.

Подытожим:

На уровне библиотек/программ/функций оставляйте комментарии, отвечая на вопрос «ЧТО?».

Внутри библиотек/программ/функций оставляйте комментарии, отвечая на вопрос «КАК?».

На уровне стейтментов оставляйте комментарии, отвечая на вопрос «ПОЧЕМУ?».

Закомментирование

Закомментировать код — это конвертировать одну или нескольких строк кода в комментарии. Таким образом, вы сможете (временно) исключить части кода от компиляции.

Читайте также:  Читы на скорость донт старв

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

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

Закомментировано символами однострочного комментария:

Закомментировано символами многострочного комментария:

Есть несколько причин, зачем использовать закомментирование:

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

Причина №2: Вы написали код, который компилируется, но работает не так как нужно и сейчас у вас нет времени с этим разбираться. Закомментируйте код, а затем, когда будет время, исправьте в нём ошибки.

Причина №3: Поиск корня ошибки. Если программа производит не те результаты (или вообще происходит сбой), полезно будет поочерёдно «отключать» части вашего кода, чтобы понять какие из них рабочие, а какие создают проблемы. Если вы закомментируете одну или несколько строчек кода и программа начнёт корректно работать (или пропадут сбои), шансы того, что последнее, что вы закомментировали, является ошибкой – очень велики. После этого вы сможете разобраться с тем, почему же этот код не работает так, как нужно.

Причина №4: Тестирование нового кода. Вместо удаления старого кода, вы можете его закомментировать и оставить для справки, пока не будете уверены, что ваш новый код работает так, как нужно. Как только вы будете уверены в новом коде, то сможете без проблем удалить старые фрагменты кода. Если же новый код у вас будет работать не так, как нужно, то вы сможете его удалить и выполнить откат к старому коду.

Примечание: Во всех следующих уроках я буду использовать комментарии в иллюстративных целях. Внимательные читатели смогут заметить, что по стандартам выше большинство из этих комментариев будут плохими. Но помните, что использовать я их буду в образовательных целях, а не для демонстрации хороших примеров.

Ссылка на основную публикацию
Как оформить список литературы в ворде
Пожалуй, любой, кому приходилось создавать список литературы знает, какая это головная боль. Сначала ищешь источники, расставляешь ссылки на них в...
Как открыть айфон без пароля
Привет, друзья! Не так давно я купил своей жене iPhone 7, а она у меня дама забывчивая и возникла проблема:...
Как открыть браузер на телевизоре samsung
Смарт-телевидение — одна из самых динамично развивающихся технологий в наше время. Smart TV значительно расширяет границы традиционного ТВ, предоставляя больше...
Как оформляются комментарии в си программе
В С все комментарии начинаются с пары символов /* и заканчиваются парой */. Между слэшем и звездочкой не должно быть...
Adblock detector