Dokumentacja jest jednym z najbardziej pożądanych, ale też najczęściej pomijanych aspektów programowania. Wymagania dotyczące dokumentacji są różne w różnych firmach. W niektórych tworzenie dokumentacji jest traktowane jako niezbędna część całego procesu produkcji oprogramowania. Zdarza się często, że niektóre firmy tworzą dokumentację już po ukończeniu programu (szczególnie gdy zamówienie ma nieprzekraczalny termin wykonania lub pod naciskiem otoczenia). W praktyce obserwuje się tendencję, że planowany jest tylko czas na wykonanie zadania, a prawie nigdy nie przewiduje się czasu na właściwy opis tego, co zostało zrobione w programie, ani tego, co miał na myśli programista piszący kod. Wszyscy programiści, którzy musieli przeglądać kod napisany przez innych, doceniają prawdopodobnie wagę tego zagadnienia.
Jeżeli nie jest to wymagane przez przepisy lub kontrakt, to dokumentacja powstaje rzadko kiedy. Często komentarze w kodzie nie odpowiadają zawartości, ponieważ kod bywa poprawiany, a komentarze nie.
Jeśli spojrzymy na to jako użytkownik, a nie programista, to także dostrzeżemy podobne zjawiska. Brak zmian w dokumentacji przy zmianach w programie prowadzi często do irytacji a nawet do poważniejszych szkód.
Na to wszystko nie ma prostej recepty. Tworzenie dokumentacji jest jak tworzenie kodu — ono także wymaga dyscypliny, aby wynik można było uznać za prawidłowy. Nauczenie się poprawnego dokumentowania programów wymaga praktyki i umiejętności krytycznej oceny swojej pracy. Z drugiej strony, dokumentacja jest jedną z najbardziej widocznych cech projektu i jeśli jest wykonana dobrze, to może przynieść dodatkowe zamówienia lub umocnić dobrą opinię o programiście.
W tym rozdziale pokażemy gdzie należy szukać użytecznych informacji o programach oraz omówimy kilka narzędzi wspomagających tworzenie własnych programów. Narzędzia te dostarczają także informacji niezbędnych do powstania dokumentacji tworzonego programu. Głównym tematem będzie tworzenie dokumentacji zewnętrznej, czyli stron podręcznika systemowego i innych dokumentów, które można wydrukować, natomiast mniejszy nacisk położymy na komentarze umieszczane w kodzie programu.
Pierwszym krokiem przy tworzeniu dokumentacji powinno być poprawne określenie jej odbiorców. Osoby użytkujące program rzadko kiedy będą zainteresowane tymi samymi zagadnieniami, co osoby odpowiedzialne za utrzymywania programu w ruchu. Można zgrubnie podzielić użytkowników dokumentacji na cztery kategorie, jednak założenia ściśle spełnione przez role użytkowników programu mogą z czasem się zmienić jeśli rozpatrujemy użytkowników dokumentacji.
q Użytkownicy: korzystają z dokumentacji głównie do celów edukacyjnych. Zadają oni pytania: Do czego służy ten przycisk? W jaki sposób dokonujemy rezerwacji? Można więc zakładać, że nigdy nie będą musieli korzystać z wiersza poleceń naszego programu.
q Zaawansowani użytkownicy i administratorzy systemu: tę kategorię odbiorców tworzą osoby zainteresowane utrzymaniem działającego programu i jego konserwacją. Z natury ich zainteresowań wynika, że chcąc wiedzieć więcej będą myśleć o błędach w działaniu programu lub o jego dostrajaniu.
q Integratorzy: do tej kategorii należą osoby biorące udział w większych projektach, w których jako elementy całości wykorzystywane są całe pakiety lub pojedyncze programy.
q Programiści: użytkownicy należący do tej kategorii będą się interesować polepszeniem funkcjonalności programu poprzez dodawanie nowych właściwości.
Użytkownicy w większości korzystają z interfejsu graficznego lub jakiejś jego namiastki. W naszej książce wiodącym tematem była do tej pory aplikacja do obsługi wypożyczalni płyt DVD, a więc tutaj również posłuży nam jako przykład. Bardzo prosto możemy wyróżnić dwa rodzaje użytkowników: personel wypożyczalni i użytkownicy łączący się ze stroną WWW wypożyczalni. Rozpoczniemy od użytkowników lokalnych.
Interfejsy graficzne najlepiej można udokumentować wyposażając aplikację w system pomocy, zawierający dużo ilustracji. Pomoc kontekstowa (czyli informacje pomocnicze zależne od tego, jaka czynność jest w danym momencie wykonywana) jest także godna uwagi. Pomoc kontekstowa może mieć różną postać, począwszy od wyświetlenia wskazówki czy wyskakującego okna z objaśnieniami, aż do specjalnego okna pomocniczego pokazującego się po naciśnięciu jakieś kombinacji klawiszy (np. CTRL-F1). Należy pamiętać, aby wszystkie elementy interfejsu graficznego i ich współdziałanie zostały udokumentowane.
Niestety, trudno jest uzyskać zwarty system pomocy. W większości pakietów pomocniczych nie ma do tego odpowiednich narzędzi i wielu programistów tworzy własne rozwiązania. W dalszej części tego rozdziału będziemy więc szukać niezbędnego minimum, które musi spełniać system pomocy w interfejsie graficznym.
Najlepszą metodą zapewnienia pomocy jest jej udostępnienie jak najbliżej tych miejsc, których ona ma dotyczyć. W Microsoft Windows oznacza to np. wskazanie jakiegoś elementu kursorem i naciśnięcie klawiszy CTRL-F1. W tym momencie pojawia się informacja pomocnicza lub w przypadku aplikacji Office — tzw. Asystent Pomocy podający „użyteczne” informacje.
Kliknięcie prawym klawiszem myszy może powodować wyświetlenie menu kontekstowego, pokazującego działania dozwolone dla wskazanego obiektu i w tym menu może się znaleźć opcja pomocy. Oczywistą zaletą kontekstowego systemu pomocy jest to, że działa on w sposób natychmiastowy. Niestety, bardzo trudno taki system wprowadzić jeżeli w pakiecie do tworzenia interfejsu graficznego nie ma narzędzia przeznaczonego do tego celu. Jeżeli programista zdecyduje się zrobić to sam, to nie ma łatwego zadania, ponieważ musi przechwytywać naciśnięcia klawiszy i ruchy myszą.
Innym rozwiązaniem jest globalna funkcja pomocy, która z oczywistych względów nie działa w sposób kontekstowy. Zazwyczaj taka pomoc w programie jest przedstawiana jako lista uporządkowanych hierarchicznie zagadnień, opisujących w mniejszym lub większym stopniu działanie programu (przeważnie jednak w mniejszym). Eleganckim kompromisem jest utworzenie takiej funkcji, w której można przejść do specyficznego zagadnienia kierując się niewielką dozą intuicji.
Całkiem zgrabną sztuczką stosowaną przy tworzeniu strukturalnego systemu pomocy jest skorzystanie z usług oferowanych przez przeglądarkę i zastosowanie formatu HTML. Przy pewnej znajomości HTML można uzyskać wynik spełniający podstawowe potrzeby, do którego można dodawać obsługę zdarzeń za pomocą języka JavaScript, zestawy ramek, arkusze stylów i inne elementy. Omawiając to rozwiązanie ograniczymy się tylko do zagadnień podstawowych, aby nie utracić ogólności rozważań.
Po naciśnięciu przycisku Help w oknie interfejsu graficznego naszej przykładowej aplikacji utworzonej w rozdziale 9. mamy tylko możliwość przeczytania dodatkowej informacji o autorach programu. Mamy zamiar dołączyć do tego nasz system pomocy. Jest to trochę bardziej skomplikowane niż dodawanie nowego przycisku (opisane także w tamtym rozdziale), ponieważ polega na dodaniu uchwytu obsługującego kod wzywający przeglądarkę HTML z adresem strony zawierającej treść pomocy.
q „Zrzuty” ekranowe: Należy utworzyć kopie obrazów każdego menu, okien dialogowych i okna głównego występujących w interfejsie graficznym. Najprostszym programem do tworzenia takich obrazków jest xwd, ale istnieją też bardziej specjalistyczne narzędzia w pakiecie ImageMagick lub autonomiczny programy xgrabsc. Aby zebrane elementy graficzne można było wykorzystać, należy zmienić ich format z xwd na format obrazu interpretowany przez przeglądarkę (może to być np. PNG). Do tego celu można użyć programów xwdtopnm i pnmtopng z zestawu narzędziowego PBMPLUS lub pakietu ImageMagick. Program GIMP także umożliwia przechwytywanie zawartości ekranu i zapis obrazu w formacie PNG lub innych.
q Strony HTML: Należy utworzyć pustą stronę HTML dla każdego wykonanego obrazu ekranowego.
q Dodanie obrazka do strony HTML: Następnie należy dodać obraz do strony HTML. Jeżeli nie jest używany edytor typu WYSIWYG, to można to uczynić używając atrybutów ISMAP i USEMAP, tak jak w poniższym przykładzie:
<IMG SRC="dvdstore.png"
ALT="Ten obrazek pokazuje wygląd okna DVDStore"
ISMAP="ismap"
USEMAP="#dvdstore-map">
rysunek ze strony 892
q Dołączenie mapy do obrazka na stronie HTML: Teraz należy utworzyć mapę do obrazu i dodać ją do strony HTML. Mapa to po prostu lista obszarów odpowiadających elementom interfejsu na obrazku. W naszym przykładzie wygląda to następująco:
<MAP NAME="dvdstore-map">
<AREA SHAPE="rect"
COORDS="102,39,186,83"
ALT="Disconnect Button"
HREF="#ExplanationOfDisconnectButton">
COORDS="200,39,299,83"
ALT="Rent Button"
HREF="#ExplanationOfRentButton">
<!-- ETC. -->
</MAP>
Opisywane obszary są zaznaczone na rysunku powyżej prostokątnymi obrysami. Cały proces może być bardzo pracochłonny, a więc nie należy się wzbraniać przed zastosowaniem takich narzędzi jak Netscape Composer.
q Dołączenie objaśnień do strony HTML: Pozostały do wykonania jeszcze tylko opisy działania każdego z przycisków. Można to zrobić tak jak w przykładowym kodzie poniżej. Dzięki temu użytkownik klikając na różne elementy obrazka na ekranie tak jakby były one przyciskami powoduje wyświetlenie odpowiedniego opisu w przeglądarce HTML. Trzeba pamiętać o użyciu zakotwiczeń w kodzie HTML odwołujących się do podanych wyżej odnośników:
<CENTER>
<A NAME="ExplanationOfDisconnectButton">
<H1>The Disconnect Button</H1>
</A>
</CENTER>
Tutaj opis przycisku Disconnect.
<P>
<A NAME="ExplanationOfRentButton">
<H1>The Rent Button</H1>
Tutaj opis przycisku Rent.
Można także dodać jakąś animację do strony HTML. Można nawet użyć zestawu ramek, umieszczając obrazek w górnej ramce, a opisy w ramkach wywoływanych kliknięciem na odpowiedni element mapy. Innymi słowy, można tutaj wykazać się pomysłowością.
Zaletą takiego sposobu dokumentowania jest to, że drukowana wersja dokumentacji elektronicznej może posłużyć jako podręcznik użytkownika. Dodatkowo, jeśli programista zdecyduje się na modyfikację interfejsu graficznego lub zastosowanie innego zestawu narzędzi albo innego środowiska programowania, to oprócz wymiany obrazków niewiele trzeba będzie zmieniać w samej dokumentacji.
Projektując interfejs WWW dla systemu korzystamy z wielu jego zalet. Po pierwsze, dołączamy do niego ograniczony zestaw funkcji, tak aby użytkownik mógł eksperymentować bez obawy o uszkodzenie danych. Mamy także dość miejsca na rozbudowane instrukcje, które w przypadku lokalnego interfejsu graficznego mogłyby przeszkadzać użytkownikowi intensywnie korzystającemu z aplikacji.
Ważne jest, aby czytelnie oznaczyć zadania spełniane przez poszczególne pola interfejsu, np. słowo „Tytuł” jest używane do oznaczenia tytułu grzecznościowego w adresach („Pan”, „Pani”) oraz tytułu zawodowego.
Dobrym zwyczajem jest dołączanie atrybutu ALT do każdego znacznika, który na to pozwala. Wówczas użytkownik przesuwając kursor nad polem edycyjnym lub przyciskiem widzi wskazówkę wyświetlaną przez przeglądarkę. Etykiety pól edycyjnych można przekształcić w odnośniki do miejsc, w których dostępne są szersze objaśnienia, tak jak w poniższym fragmencie kodu. Z prostej definicji pola do wprowadzania danych:
<TABLE>
<TR>
<TD>Your name:
<TD><INPUT TYPE="text" NAME="name" LENGTH=250>
</TABLE>
po przekształceniu uzyskujemy:
<TD><A> HREF="ExplanationOfNameField">Your name:</A>
<TD><INPUT TYPE="text" NAME="name" ALT="Tutaj krótki opis nazwy pola"
LENGTH=250>
Przy jakichś specyficznych operacjach ważny jest opis poszczególnych etapów działań. W naszym przykładzie procedura rezerwacji płyty DVD może zawierać dodawanie pozycji do koszyka zakupów, a następnie wysyłkę zamówienia. Te etapy powinny być wyraźnie oznakowane.
Trzeba pamiętać, że nie wszystkie przeglądarki działają jednakowo. Niektóre osoby mogą także oglądać naszą stronę WWW na komputerze podręcznym, inne w telefonie komórkowym WAP albo na podobnych urządzeniach z ograniczonymi możliwościami wyświetlacza. To wszystko trzeba przewidywać tworząc dokumentację elektroniczną do programu.
Zaawansowany użytkownik lub administrator systemu będzie w większości przypadków wiedział o wiele więcej o działaniu systemu niż inni. W swojej pracy przeważnie będzie on korzystał z dodatkowych programów, które nie zawsze są wyposażone w interfejs graficzny. Zasady tworzenia dokumentacji programów z interfejsem graficznym podane w poprzednim podrozdziale dotyczą także tej kategorii użytkowników. Zmienia się jedynie zakres omawianych zagadnień, a więc teraz zajmiemy się innym rodzajem dokumentacji, przeznaczonej dla zaawansowanych.
Podczas posługiwania się narzędziami korzystającymi z wiersza poleceń zdarza się dosyć często, że potrzebna jest jakaś rzadko używana opcja lub wyświetlenie listy wszystkich dostępnych opcji programu. W grupie programów narzędziowych GNU wszystko jest ułatwione, ponieważ każdy program ma opcję --help, po użyciu której nastąpi wyświetlenie listy opcji (w mniej lub bardziej skrótowej formie). Przykładowo użyjemy w taki sposób polecenia cat:
$ cat --help
Usage: cat [OPTION] [FILE]...
Concatenate FILE(s), or standard input, to standard output.
-A, --show-all equivalent to -vET
-b, --number-nonblank number nonblank output lines
-e equivalent to -vE
-E, --show-ends display $ at end of each line
-n, --number number all output lines
-s, --squeeze-blank never more than one single blank line
-t equivalent to -vT
-T, --show-tabs display TAB characters as ^I
-u (ignored)
-v, --show-nonprinting use ^ and M- notation, except for LFD and TAB
--help display this help and exit
--version output version information and exit
With no FILE, or when FILE is -, read standard input.
Report bugs to <bugtextutils@gnu.org>.
Na podstawie tego przykładu możemy stwierdzić, że pomoc dostępna z wiersza poleceń powinna zawierać co najmniej następujące pozycje:
q Nazwa: oznacza nazwę programu. Tę informację często kieruje się do pliku, a więc użycie nazwy programu może posłużyć w tym pliku jako punkt odniesienia.
q Sposób użycia: informacja powinna podawać wykaz używanych opcji i argumentów programu. Należy czytelnie oznaczyć, które argumenty są obowiązkowe, które są opcjonalne oraz podać ich kolejność, jeśli jest to istotne.
q Szczegółowe informacje o sposobie korzystania: Przy niewielkiej liczbie argumentów obsługiwanych przez program można tu podać w kolejnych wiersza opisy wszystkich opcji i argumentów. Trzeba przy tym zwrócić uwagę na to, aby nie cytować całego podręcznika systemowego. Jedna lub dwie strony informacji na ekranie powinny stanowić maksimum, które może być efektywnie wykorzystane do szybkiego zapoznania się z tematem. Więcej niż jedna strona tekstu wymaga zastosowania dodatkowych narzędzi przy przeglądaniu, np. more, less lub most, co może być męczące.
Użytkownicy chcący skorzystać z programu mają możliwość szybkiego uzyskania skróconych informacji za pomocą opcji --help. Jeżeli potrzebne są informacje bardziej szczegółowe, to zazwyczaj są one podawane w postaci tzw. stron podręcznika systemowego (manpage).
Strony te są jedną z najstarszych postaci dokumentacji elektronicznej i można je znaleźć już w najwcześniejszych wersjach systemu UNIX.
Strona podręcznika systemowego może być wyświetlona za pomocą polecenia man. Aby dowiedzieć się, jak to działa, należy użyć polecenia man man. Wkrótce przedstawimy sposób tworzenia własnych stron podręcznika systemowego, ale najpierw podamy podstawowe informacje.
Polecenie man ma swojego krewniaka w postaci polecenia apropos, które pomaga w lokalizacji informacji na podstawie słów kluczowych, a nie nazwy programu. Zazwyczaj apropos jest aliasem dla polecenia man -k. Można tu podawać dowolne słowa kluczowej jako argumenty, a w wyniku zostanie wyświetlona lista odpowiednich programów lub stron podręcznika systemowego. Oto przykład:
$ apropos noweb
nodefs (1) - find definitions in noweb file
noindex (1) - build external index for noweb document
noroots (1) - print roots of noweb file
notangle (1) - noweb, a literate-programming tool
nountangle (1) - noweb, a literate-programming tool
noweave (1) - noweb, a literate-programming tool
noweb (1) - a simple literate-programming tool
nowefilters (7) - filters and parsers for use with noweb
nowestyle (7) - LaTeX package for noweb
nuweb2noweb (1) - convert nuweb files to noweb form
Strony podręcznika systemowego utworzono dla zróżnicowanych programów, począwszy od prostych narzędzi wywoływanych w wierszu poleceń do procedur używanych w standardowej bibliotece języka C i formatów plików używanych przez różne programy. Jeśli jednak te strony zbierzemy w całość, to dosyć szybko korzystanie z nich stanie się niewygodne. Takie strony podręcznika systemowego zawierałyby dość dużo materiału, a użytkownicy nie mogliby się w nich doszukać początku opisu danego zagadnienia. Dlatego właśnie wprowadzono sekcje podręcznika systemowego. Każda sekcja zawiera specyficzny rodzaj informacji.
Wyróżnia się tu 9 podstawowych kategorii:
1. Programy lub polecenia dostępne dla wszystkich użytkowników.
2. Wywołania systemowe (funkcje obsługiwane przez jądro).
3. Wywołania funkcji bibliotecznych (zawartych w bibliotekach systemowych).
4. Pliki specjalne (zwykle umieszczane w katalogu /dev).
5. Formaty plików i konwencje nazewnicze, np. /etc/passwd.
6. Gry.
7. Makropolecenia i zasady ich stosowania.
8. Polecenia do zarządzania systemem (zwykle zarezerwowane dla użytkownika root).
9. Funkcje jądra (niestandardowe).
Odwołania do specyficznych sekcji podręcznika systemowego są zazwyczaj oznaczane przez podanie numeru sekcji w nawiasach. Pisząc więc o poleceniu man można użyć zapisu man(1), ponieważ mamy na myśli program (lub polecenie wydawane z wiersza poleceń).
Zdarza się, że program i funkcja biblioteczna mają te same nazwy, jak np. printf. Aby więc wyświetlić stronę podręcznika systemowego z opisem programu printf, należy użyć polecenia:
$ ...
kicaniec