DOKUMENTACJA PROGRAMU
Dokumentacja programu składa się z dwóch części:
- podręcznika użytkownika
- dokumentacji technicznej.
Podręcznik użytkownika jest przeznaczony dla przyszłych użytkowników programu.
Powinien on zawierać podstawowe informacje o programie, w szczególności pełny
opis sposobu korzystania z programu.
Dokumentacja techniczna stanowi najszerszy opis programu. Powinna ona zawierać
pełny zestaw szczegółowych informacji dotyczących budowy i działania programu.
Podręcznik użytkownika
1. Informacje ogólne
1.1. Autor, data opracowania podręcznika.
1.2. Krótki opis programu.
1.3. Spis treści.
2. Charakterystyka problemu
2.1. Teoretyczne wprowadzenie.
2.2. Opis notacji stosowanej w dokumentacji.
2.3. Dokładne sformułowanie problemu.
2.4. Przegląd zastosowań programu.
3. Środowisko programu
3.1. Dane wejściowe (znaczenie, format, sposób wprowadzania, warunki
poprawności, reakcja na błędy w danych).
3.2. Komunikacja z użytkownikiem (jw.)
3.3. Wyniki (jw.)
3.4. Przykłady danych wejściowych i wyników programu.
4. Sytuacje niepoprawne
4.1. Wykaz komunikatów diagnostycznych.
4.2. Błędy wykonania (opis błędu, warunki jego powstania).
5. Literatura
Dokumentacja techniczna
1.1. Autor, data opracowania dokumentacji.
2. Charakterystyka programu
2.1. Przeznaczenie programu
2.2. Przegląd zastosowań programu
3. Struktura programu
3.1. Opis plików zewnętrznych (organizacja, użycie).
3.2. Globalne struktury danych (opis, przeznaczenie, użytkownicy).
3.3. Podział na moduły, schemat komunikacji między modułami.
3.4. Wykaz używanych modułów systemowych.
4. Opis modułu
4.1. Informacje ogólne (zwięzła charakterystyka modułu).
4.2. Opis funkcjonalny modułu
4.2.1. Przeznaczenie modułu.
4.2.2. Sposób wykorzystania modułu
(procedury - przeznaczenie, parametry, sekwencja wołania;
moduły korzystające z opisywanego modułu).
4.2.3. Korzystanie z innych modułów i nielokalnych struktur danych.
4.3. Charakterystyka działania modułu
4.3.1. Szczegółowy opis algorytmu.
4.3.2. Lokalne struktury danych.
4.3.3. Budowa modułu (procedury pomocnicze - przeznaczenie, parametry,
korzystanie z nielokalnych struktur danych).
4.3.4. Wymagania czasowe i pamięciowe modułu.
4.4. Sytuacje niepoprawne
4.4.1. Kontrola poprawności danych wejściowych.
4.4.2. Wykaz komunikatów diagnostycznych.
4.4.3. Błędy wykonania (opis błędu, warunki jego powstania).
6. Załączniki
6.1. Informacja o przebiegu testowania modułów.
6.2. Przykładowe testy programu (dane testowe + omówienie testu).
6.3. Wydruk programu.
Wymagania dotyczące tekstu programu
Tekst programu powinien być czytelny i przejrzysty.
Każdy program powinien zatem zawierać:
1. Znaczące (acz krótkie) nazwy obiektów
2. Komentarze
2.0. Na początku programu komentarz z imieniem i nazwiskiem autora,
data oraz krótki opis programu.
2.1. Zwięzły opis ważniejszych obiektów (w miejscu deklaracji lub w
miejscu pierwszego użycia).
2.2. Procedury:
- przeznaczenie,
- opis parametrów,
- wykaz używanych zmiennych globalnych z zaznaczeniem sposobu
korzystania (odczyt/modyfikacja),
- założenia dotyczące poprawności wywołania.
2.3. Objaśnienie wyróżnionych fragmentów programu (np. wczytanie
danych, znalezienie elementu minimalnego).
2.4. Krótkie objaśnienia ważniejszych pętli, instrukcji warunkowych
(nie w postaci opisu działania instrukcji, np. zwiększenie x o y,
gdyż to widać z kodu, lecz opis znaczenia danej instrukcji, np.
indeks następnego elementu do zbadania).
Komentarze powinny w jak najbardziej zwięzły sposób informować o wszystkich
najważniejszych kwestiach. Powinny to raczej być równoważniki zdań niż
rozwlekła proza.
3. Układ graficzny programu
3.1. Puste linie dzielące program na sensowne jednostki.
3.2. Sensowny podział kodu programu na wiersze (unikanie długich
wierszy, a w razie konieczności właściwy ich podział).
3.2. Akapitowanie.
Akapitowanie powinno wyraźnie odzwierciedlać wzajemne powiązania
między instrukcjami (zagnieżdżenie, struktura instrukcji
warunkowych) oraz składowymi struktur danych.
programowanie2i