Единая система программной документации

 

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

Во-первых, умение создавать программную документацию определяет профессиональный уровень программиста. Заказчик не будет вникать в тонкости и особенности даже самой замечательной программы. Заказчик будет сначала читать документацию. Большую роль играет в этом и психологический фактор. В частности, во всем мире ценилась (и ценится сейчас) былая советская школа программирования. В настоящее время программы уже не пишутся, а составляются (а это – «две большие разницы»). Так вот, созданный в «классическом» стиле пакет программной документации (ПД) создаст у заказчика или работодателя самое что ни на есть благоприятное впечатление. Тем более, если автор ПД будет избегать фраз вида «кликните на скроллбар…», «винт» и т.п. К сожалению, за подобным жаргоном обычно скрывается либо скудость мыслей, либо полная пустота. Язык ПД – это своего рода бюрократический, весьма консервативный язык. Есть в нем своя особая прелесть. Согласитесь, что термины НЖМД, НГМД, ручной манипулятор типа «мышь» звучат совсем иначе, нежели соответствующие «винт», «флоп» и просто «мышь». Появилась даже особая специальность – технический писатель, т.е. человек, умеющий создавать программную документацию.

Во-вторых, грамотно составленный (точнее, созданный) пакет ПД избавит от многих неприятностей. В частности, избавиться от назойливых вопросов и необоснованных претензий можно просто предоставив пользователю документацию. Это касается, прежде всего, важнейшего документа – Технического задания. Например, многомиллионный иск к компании IBM. Этот иск предъявило одно крупное издательство, неудовлетворенное качеством ВТ и программного обеспечения. IBM суд выиграла. И выиграла только благодаря тому, что предъявила подписанное обеими сторонами Техническое задание. Было это давно, еще в 70-х гг., однако сути дела это не меняет.

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

Единая система программной документации - комплекс государственных стандартов, устанавливающих взаимоувязанные правила разработки, оформления и обращения программ и программной документации.

Стандарты ЕСПД определяют общие положения и основополагающие стандарты, правила выполнения документации разработки, правила выполнения документации изготовления, правила выполнения документации сопровождения, правила выполнения эксплуатационной документации, правила обращения программной документации и прочие стандарты. [29]

Итак, ЕСПД – это комплекс государственных стандартов устанавливающих взаимосвязанные правила разработки и обращения программ и программной документации.

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

В состав ЕСПД входят:

- основополагающие и организационно методические стандарты;

- стандарты, определяющие форму и содержание программных документов применяемых для обработки данных;

- стандарты, обеспечивающие автоматизацию разработки программных документов.

Стандарты ЕСПД упорядочивают процесс документирования программных систем. Основная часть комплекса ЕСПД была разработана в 70-е и 80-е годы. Частично эти стандартны морально устарели, к тому же они не лишены некоторых недостатков. Во-первых, в них не отражены некоторые современные тенденции оформления программ и программной документации, во-вторых, в этих стандартах наличествует многократное дублирование фрагментов программной документации. Тем не менее, за неимением лучшего ориентироваться приходится именно на них.

Стандарты ЕСПД носят рекомендательный характер.

Стандарты ЕСПД разделяются на группы:

- 0 код - группы об общем положении;

- 1 код  - группы основополагающей стандартов;

- 2 код - правила выполнения документации разработки;

- 3 код - правила выполнения документации изготовителя;

- 4 код - правила выполнения документации сопровождения;

- 5 код - правила выполнения эксплуатационных документов;

- 6 код - правила обращения программной документации;

- 7-8 резервные группы;

- 9 прочие стандарты.

Обозначение стандартов ЕСПД строятся по классификационному признаку.

В обозначении стандартов ЕСПД должны входить:

- цифры 1 и 9 присвоены классу стандартов ЕСПД;

- одна цифра после точки (.), обозначающая код классификационной группы стандартов;

- двузначное число, определяющее порядковый номер группы;

- двузначное число после тире (-) указывающее год регистрации стандартов (рисунок 27.1).

 

Рисунок 27 – Схемы алгоритмов программ данных и систем

 

Вообще перечень документов ЕСПД очень обширен. В него, в частности, входят следующие ГОСТы:

1. ГОСТ 19.001-77 ЕСПД. Общие положения.

2. ГОСТ 19.101-77 ЕСПД. Виды программ и программных документов (переиздан в ноябре 1987г с изм.).

3. ГОСТ 19.102-77 ЕСПД. Стадии разработки.

4. ГОСТ 19.103-77 ЕСПД. Обозначение программ и программных документов.

5. ГОСТ 19.104-78 ЕСПД. Основные надписи.

6. ГОСТ 19.105-78 ЕСПД. Общие требования к программным документам.

7. ГОСТ 19.106-78 ЕСПД. Требования к программным документам, выполненным печатным способом.

8. ГОСТ 19.201-78 ЕСПД. Техническое задание. Требования к содержанию и оформлению.

9. ГОСТ 19.202-78 ЕСПД. Спецификация. Требования к содержанию и оформлению.

10. ГОСТ 19.301-79 ЕСПД. Программа и методика испытаний.

11. ГОСТ 19.401-78 ЕСПД. Текст программы. Требования к содержанию и оформлению.

12. ГОСТ 19.402-78 ЕСПД. Описание программы.

13. ГОСТ 19.404-79 ЕСПД. Пояснительная записка. Требования к содержанию и оформлению.

14. ГОСТ 19.501-78 ЕСПД. Формуляр. Требования к содержанию и оформлению.

15. ГОСТ 19.502-78 ЕСПД. Описание применения. Требования к содержанию и оформлению.

16. ГОСТ 19.503-79 ЕСПД. Руководство системного программиста. Требования к содержанию и оформлению.

17. ГОСТ 19.504-79 ЕСПД. Руководство программиста.

18. ГОСТ 19.505-79 ЕСПД. Руководство оператора.

19. ГОСТ 19.506-79 ЕСПД. Описание языка.

20. ГОСТ 19.508-79 ЕСПД. Руководство по техническому обслуживанию. Требования к содержанию и оформлению.

21. ГОСТ 19.604-78 ЕСПД. Правила внесения изменений в программные документы, выполняемые печатным способом.

22. ГОСТ 19.701-90 ЕСПД. Схемы алгоритмов, программ, данных и систем. Условные обозначения и правила выполнения.

23. ГОСТ 19.781-90. Обеспечение систем обработки информации программное.