Документування програмного забезпечення

Інформатика, програмування

Коледж інформатики та обчислювальної техніки

Факультет програмування

РЕФЕРАТ

Дисципліна: технологія програмування.

Тема: документування програмного забезпечення.

Виконав студент:

Таллінн

2003

Зміст

1. Документування програмного забезпечення.

1.1 Технічне завдання.

1.2 Зовнішні та внутрішні мови специфікації.

1.3 Керівництво користувача.

1.4 Керівництво програміста .

Документування програмного забезпечення

Коли програміст-розробник отримує в тій чи іншій формі завдання напрограмування, перед ним, перед керівником проекту і перед усієюпроектною групою постають питання: що має бути зроблено, крім власнепрограми? що і як має бути оформлено у вигляді документації? щопередавати користувачам, а що - служби супроводу? як управляти всімцим процесом? Крім згаданих питань є й інші, наприклад, щомає входити в саме завдання на програмування? Минуло багато років,програмування відбувається в середовищі абсолютно нових технологій, багатопрограмісти, працюючи в стилі drag-and-drop, можуть роками не бачити текстсвоїх програм. Це не значить, що зникла потреба в їхдокументуванні. Більше того, питання про наявність хоч якийсь системи,регламентує цей бік створення програмних засобів, продовжуютьзадавати постійно. Запитують і про те, чи є обов'язкові для застосуваннястандарти (особливо гостро стоїть це питання, коли розробка виконуєтьсяна замовлення державної організації чи підприємства). Цікавляться і тим,де можна купити наявні стандарти.

Якість програмного забезпечення, поряд з іншими факторами,визначається повнотою і якістю пакета документів, що супроводжують ПЗ. Допрограмних документів відносяться документи, що містять відомості,необхідні для розробки, виготовлення, супроводження програм іексплуатації.

Технічне завдання

Технічне завдання. Вимога до змісту та оформлення. Нагадаємо,що технічне завдання (ТЗ) містить сукупність вимог до ПС і можевикористовуватися як критерій перевірки та приймання розробленої програми.
Тому досить повно складене (з урахуванням можливості внесеннядодаткових розділів) і прийняте замовником і розробником, ТЗ єодним з основоположних документів проекту програмного засобу.

Технічне завдання на розробку ПЗ повинно включати наступні розділи:вступ;підстави для розробки;

призначення розробки;

вимоги до програми;

вимоги до програмної документації;

техніко-економічні показники;

стадії і етапи розробки;

порядок контролю та приймання;

програми.

Залежно від особливостей розробляється ПО стандарт допускаєуточнення змісту розділів, введення нових розділів або їх поєднання.
У розділі "Вступ" вказується найменування, коротка характеристикаобласті застосування ПЗ.
У розділі "Підстави для розробки" вказується:

документ (документи), на основу яких ведеться розробка;

організація, що затвердила документ, і дата затвердження;

найменування (умовне позначення) теми розробки.

У розділі Призначення розробки повинно бути вказано функціональне таексплуатаційне призначення ПЗ.

Наприклад, UML - як універсальна мова моделювання. Може використовуватисяі для постановки технічного завдання.

Зовнішні і внутрішні мови специфікації

У процесі розробки ПЗ з'являються наступні документи, наведені нижчев хронологічному порядку:

Угода про вимоги;

Зовнішня специфікація;

Внутрішня специфікація.

Документ "Угода про вимоги" повинен містити перша письмоваугоду між замовником і розробником про те, що буде зроблено, і щоне буде робитися при розробці та виробництві програмного забезпечення. Увідміну від нього специфікація на увазі наявність більш точних івичерпних формулювань і визначень. При цьому, перші два документимістять інформацію про те, що являє собою ПЗ; а третій повиненпояснювати, як ВО влаштовано і як досягаються встановлені для нього мети івимоги. Всі документи мають схожу структуру для полегшення контролюнад проектом, а також для забезпечення простежуваність всіх технічнихрішень від вимог до їх реалізації. У міру просування проекту розділидокумента або просто копіюються у відповідні розділи наступногостворюваного документа, або розширюються описами технічних рішеньпоточного етапу.

Нижче наведена загальна структура документа "Зовнішня специфікація", зрозгорнутими коментарями в тих пунктах, які стосуються технічноїсторони справи
1. ОПИС ПРОГРАМНОГО ВИРОБИ
1.1. Найменування і шифри ПЗ (повне найменування, скороченінайменування, шифри ПЗ та проекту).
1.2. Короткий опис ПЗ (включаючи відомості про авторське право, ієрархіюдокументів, із зазначенням документів вищіх рівнів).
1.3. Результуючі компоненти ПЗ (оформляється у вигляді таблиці або іншийформи і включає в себе, перелік специфікацій, іншої документації ікомпонентів програмного забезпечення).
2. ЦІЛІ
Цей розділ містить причини випуску ПЗ з зазначенням різного типу заявок,планів і т.п. і носить повністю управлінський характер.
3. СТРАТЕГІЯ
3.1. Угоди щодо подання матеріалу.
3.1.1. Розташування (визначаються всі позначення, які використовуються ввимоги: наприклад, якщо застосовуються індекси, то дається приклад їхвикористання і визначається принцип індексації).
3.1.2. Термінологія (особливо специфічна для даного виробу).
3.1.3. Синтаксис (наводяться, якщо необхідно, синтаксичні правила дляподальшого опису вимог).
3.2. Генерується програмне забезпечення (класифікується якдопоміжне і породжене описуваним виробом).
3.3. Системне програмне забезпечення (все інше ПЗ, включаючи ОС,утиліти, пакети прикладних програм, яка класифікується як основне,оскільки воно генерує ПО попереднього пункту).
Примітка. Причина такої розстановки пунктів полягає в тому, що приправильному проектуванні зверху вниз генерується програмне забезпеченняє основною метою проектування і має бути описано раніше, ніжйого генератор. Іншими словами, структура генеруються програм повиннавизначати структуру генератора, а не навпаки. Якщо всі ПЗ єосновним, то в п.3.2. робиться позначка не використовується і опускаються всі йогопідпункти. Структура підпунктів п.п. 3.2 и 3.3 повністю дублюється ідалі для простоти використовується нумерація тільки п.п. 3.3.
3.3.n. Загальні характеристики функції n. Якщо технічно важко інеприродно ПО розглядати як один великий функціональний модуль, тослід привести його функціональну декомпозицію, показавши зв'язку міжфункціями (функціональними модулями) і присвоївши кожної функції деякийунікальне ім'я n. Потім для кожної функції відводиться підрозділ розділу 3.3
(тобто 3.3.1, 3.3.2 і т.д.), у заголовку якого використовується слово функціяз наступним ім'ям функціонального модуля. Така функціональнадекомпозиція не вказує, як саме ПЗ буде фактично розбито напрограмні модулі (це складає зміст документа Внутрішняспецифікація). Для зручності роботи, звичайно, корисно мати деякийвідповідність функціонального та фактичного розбиття, але це не євимогою і не повинно відводити з правильного шляху проектування виробу.
3.3.n.1. Зовнішні обмеження.
3.3.n.1.1. Стандарти (список використовуваних промислових стандартів івласних стандартів підприємства).
3.3.n.1.2. Обмеження на сумісність. Необхідно розглядати кількааспектів сумісності:вихідний мову, машинний мова, формати даних і повідомлень, формати звітів,формати лістингів і т.п. Спеціально повинна обговорюватися сумісність зінаступними програмними виробами:виробами-попередниками (тобто такими, які користувач можезамінити новим виробом; якщо число функцій при такій заміні зменшується,то слід привести обгрунтування цього);виробами-компаньйонами (тобто відносяться до тієї ж групи засобів іякі є альтернативою);подібними виробами (тобто виконують схожі функції в інших програмнихвиробах); конкуруючими виробами (інших організацій).
3.3.n.1.3. Програмні обмеження. Описуються програмне оточеннярозробляється ПЗ, включаючи вказівку коштів для його завантаження та запуску.
Також зазначаються всі діючі програмні обмеження, наприкладвикористання обчислень з подвійною точністю для деяких функцій.
3.3.n.1.4. Апаратні обмеження. Наводиться перелік пристроїв,необхідних для роботи ПЗ (із зазначенням мінімальної, оптимальної тамаксимальній конфігурації). Вказуються всі діючі обмеження наобладнання, наприклад, фізичні характеристики терміналу або вимогазаборони використання звукового сигнального пристрою.
3.3.n.2. Зовнішні характеристики.
Примітка. Якщо розробляється ПЗ є розширенням вже існуючого,то описуються, головним чином, його додаткові характеристики. У будь-якомувипадку найбільшу увагу слід приділяти найважливішим для кінцевогокористувача питань. Ці розділи є основою документа і містятьповне й остаточне опис усіх властивостей програмного виробу.
3.3.n.2.1. Результати. Описуються всі вихідні дані ПЗ з точки зору їхфункціонального змісту і призначення (наприклад, файли, повідомлення,програмно встановлюються сигнали і переривання). При цьому повинні бутирозглянуті всі можливі в системі носії та засоби відображенняінформації. Вказуються тип, структура, формат, обсяг, розташування ідіапазон зміни. Для всіх вихідних даних, що читаються людьми (повідомлення ізвіти) повинні бути приведені зразки.
3.3.n.2.2. Процеси обробки. Описуються операції, що виконуються ПЗ в ціломуабо функціональними модулями, які розглядаються як чорний ящик. Якщообговорення йде на рівні модулів або етапів розробки, вказуються такожмодулі або етапи, необхідні для отримання певної вихідної інформації.
Точно визначаються всі можливі помилки, потенційні умови їхвиникнення і способи рестарту і відновлення. Підрозділ повиненописувати ініціацію, перетворення даних, всі варіанти завершення роботи
(нормального та аварійного).
3.3.n.2.3. Входи. Опис подібно до п. 3.3.2.1
3.3.n.3. Ергономічні характеристики.
Примітка. Цей розділ описує властивості, що забезпечують надійність,комфорт і продуктивність роботи користувачів і операторів, а також питаннябезпеки, секретності, відновлючі після збоїв, мобільності ПЗ.
Зупинимося докладніше на двох підрозділах: Надійність і Робочіхарактеристики.
У розділі Надійність (це властивість програми розуміється тут якздатність до відновлення нормальної роботи при помилки та збої в роботіобладнання) розглядаються наступні питання:захист даних користувача;ступінь захисту програм від помилок, що виникають в інших частинах системи
(наприклад, що працюють одночасно з даною програмою в іншій областіпам'яті). Слід розглянути, як можуть вплинути на роботу пропонованихпрограмних засобів такі помилки, з огляду на наступні моменти: розподілресурсів пам'яті (зазначити, якщо передбачено забезпечення ізоляції відводятьсяобластей пам'яті); зв'язок програм через загальні апаратні ресурси.
Розділ "Робочі характеристики" описує основні параметри або принципи,за якими має оцінюватися ефективність роботи програми, заможливості в кількісному вигляді із зазначенням можливих допусків. Всіпараметри повинні бути вимірюваними, до них можуть ставитисяшвидкодію, пропускна спроможність, швидкість передачі даних, витратамашинних ресурсів, час реакції (або затримки) і т.д.
3.3.n.4. Внутрішні характеристики (цей розділ повністю розширюється вдокументі "Внутрішня Специфікація", проте частково може бути заповнений зметою повного опису відповідних зовнішніх властивостей).
3.4. Внутрішні обмеження (тут мова йде про ті властивості, якікористувачеві логічно очікувати, але які з тих чи інших причин будутьвиключені з програмного виробу або потенційно залишені на розсудрозробника: наприклад, неповна взаємозамінність носіїв, відсутністьпідтримки будь-яких можливостей устаткування, тощо).
4. ВИКОРИСТОВУЮТЬСЯ МАТЕРІАЛИ (в т.ч. довідкові)
5. ПЕРЕДАЧА ЗАМОВНИКУ і введення в дію

Керівництво користувача

Під документацією користувача розуміється документація, яказабезпечує кінцевого користувача інформацією з встановлення та експлуатаціїпрограмного пакета. Під інформацією на упаковці розуміють інформацію,відтворену на зовнішній упаковці програмного пакета. Її метою єнадання потенційним покупцям первинних відомостей про програмнепакеті.

Користувацька документація програмного засобу пояснюєкористувачам, як вони повинні діяти, щоб застосувати данупрограму. Вона необхідна, якщо програма передбачає будь-якевзаємодія з користувачами. До такої документації належать документи,якими керується користувач при установці програми звідповідної налаштуванням на середу застосування, при застосуванні програмидля вирішення своїх завдань і при управлінні програмою (наприклад, коли данепрограмний засіб взаємодіє з іншими системами). Ці документичастково торкаються питань супроводження програмного засобу, але нестосуються питань, пов'язаних з модифікацією програм.
У зв'язку з цим слід розрізняти дві категорії користувачів: ординарнихкористувачів програми та адміністраторів. Ординарний користувачпрограми (end-user) використовує програму для вирішення своїх завдань (в своїйпредметної області). Це може бути інженер, який проектує технічнепристрій, або касир, який продає залізничні квитки за допомогою даноїпрограми. Він може і не знати багатьох деталей роботи комп'ютера абопринципів програмування. Адміністратор программні (system administrator)керує використанням програми ординарними користувачами таздійснює супровід програмного засобу, не пов'язане змодифікацією програм. Наприклад, він може регулювати права доступу допрограмі між ординарними користувачами, підтримувати зв'язок зпостачальниками програми або виконувати певні дії, щобпідтримувати програму в робочому стані, якщо воно включено як частину віншу систему.
Склад призначеної для користувача документації залежить від аудиторій користувачів, наякі воно орієнтоване, і від режиму використання документів. Підаудиторією тут розуміється контингент користувачів, у якого єнеобхідність у певній призначеної для користувача документації. Вдалийкористувальницький документ істотно залежить від точного визначенняаудиторії, для якої він призначений. Користувацька документаціяповинна містити інформацію, необхідну для кожної аудиторії. Під режимомвикористання документа розуміється спосіб, що визначає, яким чиномвикористовується цей документ. Звичайно користувачеві досить великихпрограмних систем потрібні або документи для вивчення програмногокошти (використання у вигляді інструкції), або для уточнення деякоїінформації (використання у вигляді довідника).
Можна вважати типовим наступний склад призначеної для користувача документації длядосить великих програмних засобів:
Загальний функціональний опис програмного засобу. Дає короткухарактеристику функціональних можливостей програмного засобу.
Призначений для користувачів, які повинні вирішити, наскількинеобхідно їм дане програмного засобу.
Керівництво з інсталяції програмного засобу. Призначено длясистемних адміністраторів. Він повинен детально наказувати, яквстановлювати системи в конкретному середовищі. Він повинен містити описмашинно-зчитує носія, на якому поставляється програмнезасіб, файли, що представляють програмний засіб, і вимоги домінімальної конфігурації апаратури.
Інструкція по застосуванню програмного засобу. Призначена дляординарних користувачів. Містить необхідну інформацію по застосуваннюпрограмного засобу, організовану у формі зручній для її вивчення.
Довідник по застосуванню програмного засобу. Призначений для ординарнихкористувачів. Містить необхідний?? ю інформацію щодо застосування програмногокошти, організовану у формі зручній для виборчого пошукуокремих деталей.
Керівництво з управління програмним засобом. Призначено длясистемних адміністраторів. Воно має описувати повідомлення, що генеруються,коли програмні засоби взаємодіє з іншими системами, і якреагувати на ці повідомлення. Крім того, якщо програмний засібвикористовує системну апаратуру, цей документ може пояснювати, яксупроводжувати цю апаратуру.
Розробка документації для користувача починається відразу після створеннязовнішнього опису. Якість цієї документації може істотно визначатиуспіх програми. Вона повинна бути досить проста і зручна длякористувача (у противному випадку це програмний засіб, взагалі, неварто було створювати). Тому, хоча чорнові варіанти (ескізи)призначених для користувача документів створюються основними розробниками програмногокошти, до створення їх остаточних варіантів часто залучаютьсяпрофесійні технічні письменники. Крім того, для забезпечення якостіпризначеної для користувача документації розроблено ряд стандартів, в якихпропонується порядок розробки цієї документації, формулюютьсявимоги до кожного виду призначених для користувача документів і визначаються їхструктура і зміст.

Керівництво програміста

Документація із супроводження програмного засобу (systemdocumentation) описує програмний засіб з точки зору її розробки.
Ця документація необхідна, якщо програмний засіб припускаєвивчення того, як вона влаштована (сконструйована), і модернізацію йогопрограм. Як уже зазначалося, супровід - це триваєрозробка. Тому в разі необхідності модернізації програмногокошти до цієї роботи залучається спеціальна команда розробників -супровідників. Цій команді доведеться мати справу з такою ж документацією,яка визначала діяльність команди первинних (основних)розробників програмного засобу, - з тією лише різницею, що цядокументація для команди розробників-супровідників буде, як правило,чужий (вона створювалася іншою командою). Команда розробників -супровідників повинна буде вивчати цю документацію, щоб зрозуміти будовуі процес розробки модернізованого програмного засобу, та внести в цюдокументацію необхідні зміни, повторюючи в значній мірітехнологічні процеси, за допомогою яких створювалося початковепрограмний засіб.
Документація із супроводження програмного засобу можна розбити на двагрупи:
1. документація, яка визначає будову програм і структур даних ПС ітехнологію їх розробки;
2. документацію, що допомагає вносити зміни в програмний засіб.
Документація першої групи містить підсумкові документи кожноготехнологічного етапу розробки програмного засобу. Вона включаєнаступні документи:
Зовнішнє опис програмного засобу (Requirements document).
Опис архітектури програмного засобу (description of the systemarchitecture), включаючи зовнішню специфікацію кожної її програми.
Для кожної програми програмного засобу - опис її модульноїструктури, включаючи зовнішню специфікацію кожного включеного до неї модуля.
Для кожного модуля - його специфікація і опис його будови (designdescription).
Тексти модулів вибраною мовою програмування (program source codelistings).
Документи встановлення достовірності програмного засобу (validationdocuments), що описують, як встановлювалася достовірність кожної програмипрограмного засобу і як інформація про встановлення достовірностіпов'язувалася з вимогами до програмного засобу.
Документи встановлення достовірності включають перш за все документацію потестування (схема тестування і опис комплекту тестів), але можутьвключати і результати інших видів перевірки програмного засобу,наприклад, докази властивостей програм.
Документація другої групи містить
Керівництво із супроводження програмного засобу (system maintenanceguide), яке описує відомі проблеми разом із програмнимзасобом, описує, які частини системи є апаратно-та програмно -залежними, і як розвиток програмного засобу прийнято до уваги в йогобудові (конструкції).
Загальна проблема супроводу програмного засобу - забезпечити, щоб усійого вистави йшли в ногу (залишалися узгодженими), коли програмнезасіб змінюється. Щоб цьому зарадити, зв'язку і залежності міждокументами і їх частинами повинні бути зафіксовані в базі даних управлінняконфігурацією.

1. http://www.ergeal.ru/archive/cs/tp/ - Технологія програмування,конспект лекцій ВМиК МГУ, кафедра системного програмування

2.http:// www.aanet.ru/ ~ web_k46/textbooks/std_pro/face.htm - Богданов Д.В.,
Путилов В.А., Фільчаков В.В. Стандартизація процесів забезпечення якостіпрограмного забезпечення. - Апатити, КФ ПетрГУ, 1997.