-----------------------------------
     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;