-----------------------------------
Dokumentacja programu semestralnego
-----------------------------------
Każdy student jest zobowiązany do opracowania:
- dokumentacji projektowej i
- dokumentacji programu.
Dokumentacja projektowa musi zostać zatwierdzona przez osobę prowadzącą
zajęcia. Jeżeli projekt nie będzie zadowalający, to należy go poprawi(a)ć
(aż do skutku). Po zatwierdzeniu projektu ewentualne jego zmiany również
wymagają akceptacji ze strony osoby prowadzącej zajęcia.
Dokumentacja programu powinna zostać dostarczona wraz z gotowym programem.
Ocenie podlega zarówno program jak i dokumentacja.
Obie dokumentacje należy dostarczyć na papierze (wystarczy napisać tekst
pod zwykłym edytorem tekstowym; ręczne przygotowanie jest akceptowalne pod
warunkiem czytelności tekstu).
Poniżej przedstawiamy podstawowe informacje o wszystkich rodzajach
dokumentacji. W przypadku większych zadań programistycznych dokumentacja
powinna być znacznie obszerniejsza niż podano poniżej. Natomiast w przypadku
zadania semestralnego niektóre z podanych składowych dokumentacji mogą być
sprowadzone do minimum, w szczególności p. 2 (charakterystyka problemu).
Dokumentacja projektowa zadania semestralnego powinna mieścić się na 2-4 (!!)
stronach standardowego maszynopisu.
=============================================================================
DOKUMENTACJA PROJEKTOWA
-----------------------
Dokumentacja projektowa powstaje w fazie projektowej procesu tworzenia
programu i stanowi materiał wyjściowy dalszych etapów programistycznych.
Stworzenie dobrej dokumentacji projektowej wymaga wnikliwej analizy zadania,
rozpatrzenia alternatywnych rozwiązań, wyboru właściwej metody rozwiązania
oraz odpowiedniej struktury całego programu.
Dokumentacja projektowa powinna zawierać:
1. Informacje ogólne
1.1. Autor, data opracowania dokumentacji.
1.2. Krótki opis przedmiotu dokumentacji.
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. Charakterystyka algorytmu
3.1. Opis metody rozwiązania.
3.2. Uzasadnienie wyboru przyjętej metody, dyskusja alternatywnych rozwiązań.
3.3. Uzasadnienie poprawności przyjętej metody, ocena złożoności rozwiązania.
4. Struktura programu
4.1. Opis głównych struktur danych.
4.2. Podział programu na moduły, komunikacja miedzy modułami, opis
funkcjonalny modułów.
4.3. Opis wejścia/wyjścia programu.
4.4. Istniejące ograniczenia.
5. Literatura
=============================================================================
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. Informacje ogólne
1.1. Autor, data opracowania dokumentacji.
1.2. Krótki opis programu.
1.3. Spis treści.
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).
5. Literatura
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.
Przykłady czytelnych fragmentów programu:
czlowiek = record
imie, nazwisko: ....;
dataur: data;
adres: record
miejsc: ...;
ulica : ...;
numer : ...;
mieszk: ...
end;
tel: ...
end;
case samochod.kolor of
bialy: umyj (samochod);
zolty: pomaluj (samochod, zielony);
fioletowy, czarny:
sprzedaj (samochod)
end;
for i := 1 to liczba_elem do
for j := 1 to liczba_elem do begin
suma := 0;
...
if suma > wart_oczek then begin
writeln ( ... );
...
end
else begin {wszystko w porządku}
...
end;
...
end;