4Требования к оформлению программных документов в соответствии со стандартами

Программные документы оформляются в соответствии с требованиями ГОСТ 19.105-78. При оформлении документов используются листы формата А4 (210×297 мм), допускается формат 297×420 мм. Текст располагается на одной стороне листа в рамке (сама рамка на листе не показывается), отстоящей от краев листа: слева - 20 мм; сверху - 25 мм; справа - 10 мм; снизу - 15 мм.

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

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

Титульная часть состоит из листа утверждений (ЛУ) и титульного листа (ТЛ), выполняемых на бумаге формата А4.

Информационная часть состоит из двух элементов: аннотации и содержания (перечня). Аннотация представляет собой краткое изложение всего программного документа. Аннотация размещается на отдельной странице. В содержание входит перечень записей о структурных элементах основной части документа.

Основная часть документа по составу и структуре устанавливается стандартами ЕСПД на соответствующие документы. Она содержит текст документа (с наименованиями разделов), рисунки, таблицы и т.п. В основную часть включают: перечень терминов и определений, перечень сокращений, приложения, предметный указатель и перечень ссылочных документов.

Разрешается делать включения в текст документа текста программы, выполненного на языке программирования. Каждую часть текстового документа необходимо начинать с титульного листа. Нумерацию страниц производят в пределах каждой части. ГОСТ 19.106-78 устанавливает три способа выполнения программных документов: машинописный (в исключениях допускается и рукописный способ); машинный (на ЭВМ); типографский.

Текст программы - обязательный программный документ для компонентов (для компонентов, не имеющих спецификации, он является основным документом). Требования к содержанию документа установлены ГОСТ 19.401-78. Информационная часть в документе является обязательной. Запись текстов в основной части документа реализуется одним из типов символической записи: на исходном языке; на промежуточных языках; символическое представление машинных кодов и т.п.

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

1) комментарии;

2) пробелы и отступы;

3) выбор имен переменных.

Комментарии следует включать в процессе написания программы, так как они нужны не только при использовании программы, но и на стадиях проектирования и отладки. Существуют три типа комментариев: вводные, оглавления и пояснительные.

Каждая программа, подпрограмма или процедура должна начинаться с комментариев, поясняющих, что она делает. Информация, содержащаяся во вводных комментариях, должна включать следующие пункты:

1) назначение программы;

2) указания по вызову программы и ее использованию;

3) список и назначение основных переменных или массивов;

4) указания по вводу-выводу. Список всех файлов;

5) список используемых подпрограмм;

6) название применяемых математических методов, а также ссылки на литературные источники, где содержится их описание;

7) сведения о времени выполнения программы;

8) требуемый объем памяти;

9) специальные указания оператору;

10) сведения об авторе;

11) дату написания программы.

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

{*************************************************** }

{ Программа KVADUR }

{ Цель }

{ Нахождение корней квадратного уравнения }

{ Программа находится в файле Lab5.pas в каталоге }

{ МОИ ДОКУМЕНТЫ/ПАСКАЛЬ }

{ Описание параметров и переменных }

{ A, B, C – коэффициенты квадратного уравнения }

{ D – дискриминант квадратного уравнения }

{ IС – переменная идентификации типа результата }

{ Х1, Х2 – корни уравнений }

{ Требуемые подпрограммы }

{ НЕТ }

{ Метод }

{ В соответствии со значениями коэффициента и }

{ дискриминанта вычисляются корни квадратного }

{ уравнения. При разных вещественных корнях }

{ используются формулы Виета. }

{ Объем памяти, занимаемой программой: 2456 байт }

{ Программист }

{ Иванов И.И. (г. Рязань, тел. 000000) }

{ Дата написания программы }

{ Март 2009 года }

{*************************************************** }

Рис. 3. Пример вводных комментариев для программы решения

квадратного уравнения

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

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

Для выявления структуры программы целесообразно использование отступов. При этом для выделения нескольких слов (или операторов) их записывают с одной позиции.

Описание программы - программный документ, который составляется на компоненты и комплексы в соответствии с требованиями ГОСТ 19.402-78. Информационная часть документа содержит общие сведения, функциональное назначение, описание логической структуры, используемые технические средства, вызов и загрузку, входные и выходные данные.

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

Пояснительная записка - программный документ, входит в состав документов на стадиях эскизного и технического проектов программы. Содержание и оформление документа регламентируется ГОСТ 19.404-79. Документ содержит схему алгоритма, общее описание алгоритма и (или) функционирования программы, а также обоснование принятых технических и технико-экономических решений.