Комментарии

Лучшей документацией внутренней логики программы являются простая и ясная структура текста программы, использование сдвига по строке в соответствии с уровнем вложенности, осмысленные имена и со­блюдение других правил, касающихся стиля программирования [1]. Если текст программы обладает этими свойствами, обилие комментариев не яв­ляется необходимым и часто даже нежелательно. Известны случаи, когда комментарии мешали отладке, поскольку человек, отлаживающий про­грамму, склонен верить им и в результате недостаточно тщательно прове­ряет текст программы. Опытные программисты, отыскивая во время от­ладки ошибку в модуле, часто закрывают комментарии листом бумаги.

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

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

Физически «выдвигайте» все комментарии из текста собственно программы.При печати комментарии следует смещать вправо от текста программы, так чтобы читатель мог просматривать программу, не преры­ваемую комментариями. Другими словами, комментарии в программе должны быть аналогичны подстрочным примечаниям в книге.

Прокомментируйте все переменные.Понимание данных – ключ к пониманию программы. Каждое предложение, объявляющее некоторую переменную, должно сопровождаться комментарием, поясняющим смысл этой переменной.

Определения данных

Понимая особую важность данных, приведем несколько правил их определения и использования [4].

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

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

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

а=sin(0,7);

следует заменить на фрагмент программы:

с=0,7;

а=sin(c);

Никогда не используйте несколько имен для одной области памяти.

Никогда не используйте переменную более чем для одной цели. Рас­пространенный прием экономии лишнего слова памяти состоит в повтор­ном использовании переменной в различных целях. Программист вполне может решить: «Я закончил работать с TIME для расчетов времени, по­этому теперь буду использовать эту переменную как промежуточную при вычислении даты». Такая практика увеличивает шансы внесения ошибок при модификации программы.

Никогда не используйте особые значения переменной с особым смыслом.В определении параметров подпрограмм часто можно увидеть комментарии вроде такого: «ДЛСТРОКИ – это число символов во входной строке, причем ДЛСТРОКИ=0 означает ошибку при вводе». Это неодно­значное употребление параметра часто приводит к двусмысленным ситуа­циям и иногда затрудняет изменение программы. Чтобы передавать код ошибки, следует определить отдельный параметр.

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

Будьте осторожны с двоичной машиной.Двоичные машины обла­дают тем свойством, что числа с плавающей точкой в них представляются приближенными значениями. В такой машине умножение 10.0 на 0.1 редко дает в результате 1.0. Программист должен остерегаться этого свойства, особенно при попытке сравнивать два числа с плавающей точкой.

Будьте осторожны с действиями над целыми.Следует быть внима­тельным при умножении или делении целых чисел. Если I – целочисленная переменная, то ответ на вопрос, равны ли между собой I и 2*I/2, зависит от того, четно I или нет и что в сгенерированной компилятором программе будет выполняться раньше: умножение или деление.

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

WinExec( '"bin\tpc.exe" ' +ListBox.Items.Strings[2]);

{запуск консольного приложения с параметром, который написан во второй строчке листбокса}

Компилятор выдает ошибку на несовместимые типы String и PAnsiChar.

Для исправления этой ошибки строку нужно привести к PChar:

WinExec(PChar('"bin\tpc.exe" ' +ListBox.Items.Strings[2])).