Главная  Полное построение алгоритма 

[0] [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20] [21] [22] [23] [24] [25] [26] [27] [28] [29] [30] [31] [32] [33] [34] [35] [36] [37] [38] [39] [40] [41] [42] [43] [44] [45] [46] [47] [48] [49] [50] [51] [52] [53] [54] [55] [56] [57] [58] [59] [60] [61] [62] [63] [64] [65] [66] [67] [ 68 ] [69] [70] [71] [72] [73] [74] [75] [76] [77] [78] [79] [80] [81] [82] [83] [84] [85] [86] [87] [88] [89] [90] [91] [92] [93] [94] [95] [96] [97] [98] [99] [100] [101] [102] [103] [104] [105] [106] [107] [108] [109] [110] [111] [112] [113] [114] [115] [116] [117]

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

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

Внешняя документация

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

В зависимости от размера и сложности программы внешняя документация может принимать различные, формы. Некоторыми такими формами являются (1) блок-схемы, (2) инструкции для пользователей, (3) образцы входных и выходных данных, (4) полное описание построения сверху-вниз, (5) словесное описание алгоритма, (6) ссылки на источники информации, (7) справочники по именам переменных и подпрограммам с указанием их ролей в данной программе и (8) обсуждение различных частных особенностей (например, результатов проверки, ограничений, истории и математического обосновавия).

Программная документация

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

Комментарии должны быть нравильными и информативными. Хотя это правило и очевидно, его часто нарушают. Рассмотрим следующий фрагмент программы:



с ПРОВЕРКА, ЕСЛИ К БОЛЬШЕ L; С ТОГДА ПЕРЕЙТИ НА 150

IF (К .GE. L) GO ТО 150

Комментарий, предшествующий оператору IF, не является ни правильным, ни информативным. Он просто повторяет оператор и не дает никакой информации относительно цели оператора IF или того, что делает оператор с меткой 150. Комментарий также создает впечатление, что оператор с меткой 150 будет выполняться, даже если К не больше L. К тому же оператор с меткой 150 исполняется при K=L. Такой комментарий хуже, чем бесполезный.

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

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

Следует использовать мнемонические имена для переменных и подпрограмм. Имена переменных и подпрограмм должны намекать иа их функцию в алгоритме. Эта практика содействует самодокументации текста программы.

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

1. Хороший описательный заголовок, имя автора, дату последнего изменения и т. д.

2. Краткое описание того, что делает программа, и, возможно, того, как она это делает (или по крайней мере соответствующие ссылки).

3. Список используемых подпрограмм с кратким описанием цели каждой из них.

4. Список и описание всех переменных, назначение которых не очевидно с первого взгляда.

5. Информацию о возвратах и умолчаниях при обнаружении ошибок.



6, Информацию о необходимых входных данных и выдаваемых выходных данных.

Для некоторых программ все упомянутое может быть необязательным. Нет нужды предварять программу из 10 операторов комментарием на 100 картах.

Мини-прологами следует снабжать большинство подпрограмм. Особое внимание следует уделять документации связей между под-программами.

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

Избегайте плохого или заумного текста программы. Лучшей документацией является ясный текст программы. Плохой или заумный текст плодит ошибки и требует дополнительной документации. Не пытайтесь компенсировать такой текст программы многочисленными комментариями; лучше перепишите программу.

Стремитесь к четкости. Легче читать ясную, правильно расположенную программу, чем продираться через перегруженную программу. Отметим несколько конкретных приемов обеспечения наглядности.

1. Упорядочивайте объявления переменных и массивов в некоторой логической последовательности или в алфавитном порядке. Это облегчает проверку, все ли переменные объявлены и правильны ли их размеры и типы.

2. Упорядочивайте номера операторов. Эти номера должны возрастать для выполняемых операторов сверху-вниз вдоль листинга программы.

3. Выделяйте отступом от начала строки фрагменты программы в соответствии с логическими уровнями; особенно после операторов DO и IF. Относительно некоторых приемов см. разд. 2.1 и приложение А.

4. Выделяйте отступом от начала строки комментарии и отделяйте их от текста программы картами пустых комментариев.

5. Пользуйтесь пробелами для облегчения чтения программы. Например,

IF (ALPHA .LE. 0.5+EPS) GO TO 100 легче читать, чем

IF(ALPHA.LE..5+EPS)G0T0 100

6. Длинные выражения разбивайте на части. Избегайте логических или арифметических выражений, занимающих большую часть карты или требующих карт проДолжейия.



[0] [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20] [21] [22] [23] [24] [25] [26] [27] [28] [29] [30] [31] [32] [33] [34] [35] [36] [37] [38] [39] [40] [41] [42] [43] [44] [45] [46] [47] [48] [49] [50] [51] [52] [53] [54] [55] [56] [57] [58] [59] [60] [61] [62] [63] [64] [65] [66] [67] [ 68 ] [69] [70] [71] [72] [73] [74] [75] [76] [77] [78] [79] [80] [81] [82] [83] [84] [85] [86] [87] [88] [89] [90] [91] [92] [93] [94] [95] [96] [97] [98] [99] [100] [101] [102] [103] [104] [105] [106] [107] [108] [109] [110] [111] [112] [113] [114] [115] [116] [117]

0.0013