Пояснительные комментарии

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

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

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

/* ПРОВЕРИТЬ, ЯВЛЯЕТСЯ ЛИ ВЕЛИЧИНА ОТРИЦАТЕЛЬНОЙ */

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

/* ВЫПОЛНИТЬ ОБРАБОТКУ ОТРИЦАТЕЛЬНОГО САЛЬДО (СУММАРНЫЕ РАСХОДЫ ПРЕВЫШАЮТ ДОХОДЫ.) */

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

комментарии должны содержать некоторую дополнительную информацию, а не перефразировать программу.

О качестве комментариев можно судить по тому, понятна ли логика программы только на основании комментариев (без обра­щения к какой-либо другой документации). Одна из причин сла­бой комментируемой программы — переоценка наших возможно­стей. Мы уверены, что легко вспомним логику той или иной части программы. Более того, мы не ожидаем большого количества оши­бок в нашей программе, и комментарии кажутся нам излишними. Однако опыт говорит об обманчивости подобных ожиданий.