Лекция: Программная документация. Требования Единой системы программной документации. Привести примеры программных документов.
Содержание и оформление работы должны отвечать следующим шести требованиям:
1. Общим требованиям к программным документам.
Общие требования к оформлению программных документов устанавливает ГОСТ 19.105-78.
Программный документ может подаваться на различных типах носителей данных и состоять из следующих условных частей:
– титульной;
– информационной;
– основной;
– регистрации изменений.
Титульная часть состоит из листа утверждения и титульного листа согласно ГОСТ 19.104-78.
Информационная часть состоит из аннотации и содержания. В аннотации указывают сведения о назначении документа и сжатое изложение его основной части.
Содержание содержит перечень записей о структурных элементах основной части документа, в каждую из которых входят:
– обозначения структурного элемента (номер раздела, подраздела);
– наименование структурного элемента;
– адрес структурного элемента на носителе данных (например, номер страницы, номер файла и т.д.).
Правила обозначения структурных элементов основной части документа и их адресации устанавливают стандарты ЕСПД для каждого типа носителя. Состав и структуру основной части программного документа устанавливают правила ЕСПД на соответствующие документы. О каждом изменении программного документа делают запись согласно ГОСТ 19.603-78.
2. Требованиям к описанию языка.
Требования к содержанию и оформлению программного документа по описанию языка (программирование, управление заданием, организация вычислительного процесса) устанавливает ГОСТ 19.506-79. При этом учитываются положения ГОСТ 19.105-78 «Общие требования к программным документам». Составление информационной части (аннотации и содержания) является обязательным.
Описание языка должно содержать следующие разделы.
1. Общие сведения. Указывают назначение и дают описание общих характеристик языка, его возможностей, основных сфер использования и т.д.
2. Элементы языка. Дают описание синтаксиса и семантики базовых и составляющих элементов языка.
3. Способы структурирования программы. Указывают способы вызова процедуры, передачи управления и другие элементы структурирования программы.
4. Средства обмена данными. Указывают описание Языковых средств обмена данными (например, средства ввода-вывода, внутреннего обмена данными и т.д.).
5. Встроенные элементы. Дают описание встроенных в язык элементов (например, функции, классы и т.д.) и правила их использования.
6. Средства отладки программ. Указывают описание наличных средств отладки программ, семантику этих средств, рекомендации относительно их использования.
В случае необходимости содержание разделов можно пояснять примерами. В приложениях к описанию языка можно указывать вспомогательные материалы (формализованные описания языковых средств, иллюстрации, таблицы, графики, формы бланков и т.д.).
3. Требованиям к тексту и описанию программы.
Структуру и оформление текста программы устанавливают в соответствии с ГОСТ 19.105-78 «Общие требования к программным документам». Составление информационной части (аннотации и содержания) является обязательным.
Основная часть документа должна состоять из текстов, одного или нескольких разделов, которым дают наименование. Каждый из этих разделов реализуется одним из типов символической записи, например:
– символические записи исходными или промежуточными языками;
– символическое представление машинных кодов и т.д.
В символическую запись разделов рекомендуется включать комментарии, которые могут отображать, например, функциональное 'назначение, структуру (ГОСТ 19.401-78).
Описание программы должно содержать следующие разделы (ГОСТ 19.402-78):
1. Общие сведения. Указывают обозначение и наименование программы; программное обеспечение, необходимое для функционирования программы; язык программирования, которым написана программа.
2. Функциональное назначение. Указывают классы решаемых задач и (или) назначение программы и сведения о функциональных ограничениях программы.
3. Описание логической структуры. Указывают алгоритм программы, использованные методы, структуру программы с описанием функций составляющих частей и связи между ними. Описание логической структуры программы выполняют с учетом текста программы на исходном языке.
4. Использованные технические средства. Перечисляют типы ЭВМ и устройства, используемые для работы программы.
5. Вызов и загрузка. Указывают способ вызова программы с соответствующего носителя данных, входные точки программы. Допускается указывать адреса загрузки, сведения об использовании оперативной памяти, объем программы.
6. Входные данные. Указывают характер, организацию и предварительную подготовку входных данных, а также формат и способ кодирования входных данных.
7. Выходные данные. Указывают характер и организацию выходных данных, а также формат и способ кодирования выходных данных.
Допускается содержание разделов иллюстрировать пояснительными примерами, таблицами, схемами, графиками. В приложениях к описанию программы допускается указывать различные материалы, которые нецелесообразно указывать в описании программы.
4. Требования к пособию системного программиста.
Требования к содержанию и оформлению программного документа «Пособие системного программиста» устанавливает ГОСТ 19.563-79. При этом учитываются положения ГОСТ 19.105-78 «Общие требования к программным документам». Составление информационной части (аннотации и содержания) является обязательным.
Пособие системного программиста должно содержать следующие разделы.
1. Общие сведения о программе. Указывают назначение и функции программы и сведения о технических и программных средствах, которые обеспечивают выполнение этой программы.
2. Структура программы. Указывают сведения о структуре программы, ее составные части и связи между ними и другими программами.
3. Настройка программы. Указывают описание действий по настройке программы на условия конкретного использования (настройка на состав технических средств, выбор функций и др.).
4. Проверка программы. Указывают описание способов проверки, позволяющие оценить работоспособность программы (контрольные примеры, методы прогона, результаты).
5. Сообщения системному программисту. Указывают тексты сообщений, выдаваемых в ходе выполнения настройки и т.п.
В приложениях к пособию можно указывать вспомогательные материалы (примеры, иллюстрации, таблицы, графики и т.д.).
5. Требования к пособию программиста.
Требования к содержанию и оформлению «Пособия программиста» устанавливает ГОСТ 19.504-79. При этом учитываются положения ГОСТ 19.105-78 «Общие требования к программным документам». Составление информационной части (аннотация и содержание) является обязательным.
Пособие программиста должно содержать следующие разделы.
1. Назначение и условия использования программы. Указывают назначение и функции, которые должна выполнять программа, и условия, необходимые для выполнения программы (объем оперативной памяти, требования к составу и параметрам периферийных устройств, программного обеспечения и т.д.).
2. Характеристика программы. Описывают основные характеристики и особенности программы (временные характеристики, режим работы, средств контроля и т.д.).
3. Обращение к программе. Указывают описание процедур вызова программы (способы передачи управления и параметров данных и т.д.).
4. Входные и выходные данные. Представляют описание организации используемой входной и выходной информации.
5. Сообщения. Указывают пакеты сообщений, выдаваемые программисту или оператору в ходе выполнения программы, описание их содержания и действия, которые необходимо выполнять по этим сообщениям.
В приложениях можно указывать вспомогательные материалы (примеры, иллюстрации, таблицы, графики и т.д.).
6. Требования к ТЗ.
Порядок построения и оформления ТЗ на разработку программы или программного изделия устанавливает ГОСТ 19.201-78.
Техническое задание содержит следующие разделы.
1. Вступление. Указывают наименование, сжато характеризуют сферу использования программы (изделия) и объекта.
2. Основания для разработки.
В этом разделе указывают:
– документ, на основании которого выполняется разработка;
– организации, утвердившие этот документ;
– наименование и (или) условное обозначение цели разработки.
3. Назначение разработки. Указывают функциональное и эксплуатационное назначение программы (изделия).
4. Требования к программе или программному изделию.
Этот раздел состоит из следующих подразделов:
– требования к функциональным характеристикам и надежности;
– требования к составу и параметрам технических средств, их информационной и программной совместимости;
– условия эксплуатации, специальные требования.
5. Требования к программной документации. Указывают предварительный состав программной документации и, в случае необходимости, специальные требования к ней.
6. Технико-экономические показатели.
В этом разделе указывают:
– ориентировочную экономическую эффективность;
– предусмотренную потребность на год;
– экономические преимущества в сравнении с лучшими образцами (аналогами).
7. Стадии и этапы разработки. Устанавливают необходимые стадии разработки, этапы и содержание работ (перечень программных документов, которые должны быть разработаны, согласованы и утверждены), а также термины разработки, определяют исполнителей.
8. Порядок контроля и приемки. Указывают виды испытаний и общие требования к приемке работ.
В приложениях к ТЗ в случае необходимости указывают:
– перечень научно-исследовательских и других источников и работ, обосновывающих разработку;
– схемы алгоритмов, таблицы, описания, обоснования, расчеты и другие документы, которые могут быть использованы в разработке.