Dokumentacja do kodu
Tristan Alder
dokumentacji do kodu, a ja nie mam zielonego pojęcia, jak się to robi.
Zmienne i procedury nazywam zawsze wg ich znaczenia. Wydawało mi się,
że źródła są logiczne. Ale nabywca mówi:
->>>
Myślę, że dokumentacja choćby i nie potrzebna ze względu na
"łopatologicznie" wyjaśnione źródło musi być. Takie są przyjęte
standardy przekazywania kodów oraz programów tylko i wyłącznie ze
źródłami. Nigdy nie możemy wykluczyć, że będą się tym zajmowały osoby
mające trudności interpretacyjne kodów źródłowych.
->>>
Proszę o pomoc. Jak powinna wyglądać taka dokumentacja? Wszystko ma
być opisane? Osobno? Czy ktoś z Was ma doświadczenie, jak to się robi?
--
Tristan hrabia Alder
Robert Razniewski
Po pierwsze nie ma standardów przekazywania kodów. Są tylko umowy między
kupującym a sprzedającym. Jak nie było w umowie, to nie ma w ogóle i
cześć.
Ale jeżeli jesteś przyparty do muru, to:
0. Zdefiniuj przeznaczenie programu.
1. Zrób opis modułów lub warstw programu. Opisz ich przeznaczenie (np.
user interface, poszczególne formy, zestaw funkcji do obsługi bazy danych
itd).
2. Opisz złącza między modułami/warstami.
3. Wybierz z każdego modułu zestaw funkcji/procedur strategicznych i opisz
ich działanie.
4. Opisz ew. strukturę bazy danych lub strukturę plików generowanych lub
czytanych przez program.
5. Jeśli korzystasz ze standardów (protokoły itp.) podaj je razem z
oznaczeniami wersji.
6. Podaj zestaw obcych komponentów (z oznaczeniami wersji i miejscami,
gdzie są dostępne) potrzebnych do skompilowania całości.
7. Nie opisuj znaczenia funcji max(a, b) lub tp. Szkoda czasu.
8. I czółko.
9. Uzyskaj od swojego upierdliwego klienta pisemny protokół przekazania z
klauzulą, że źródła oddajesz w całości i od tego momentu nie odpowiadasz
za nic.
rr
Sławomir Adamski
dyskusyjnych napisał:3945551C...@inet.com.pl...
> Tristan Alder wrote:
>
> > Sprzedałem ostatnio źródła mojego programu. Nabywca domaga się
> > dokumentacji do kodu, a ja nie mam zielonego pojęcia, jak się to robi.
> > Zmienne i procedury nazywam zawsze wg ich znaczenia. Wydawało mi się,
> > że źródła są logiczne. Ale nabywca mówi:
Spróbuj wyczuć, czy chodzi o prawdziwą dokumentację, czy też tylko o
podkładkę (pod fakturę np.) Jeśli to pierwsze, to przepis Roberta jest w
miarę sensowny. Jeśli to drugie, to kombinuj, aby było dużo papieru -
struktury baz danych, spis procedur i parę słów, do czego aplikacja, do
której źródła sprzedałeś, ma służyć. To, do czego jej użyć, to na
początku - krótko we wstępie, potem procedury i struktury, a na koniec
rozwinięcie wstępu. Wymacaj, czy takie coś zadowoli klienta - być może, że
jeszcze parę słów o przeznaczeniu procedur i funkcji oraz coś o
przeznaczeniu pól w strukturach i chwacit.
--
Sławek
Traptak
<3945551C...@inet.com.pl>...
>Tristan Alder wrote:
>
>>[...]
>
>[...]
>Ale jeżeli jesteś przyparty do muru, to:
>0. Zdefiniuj przeznaczenie programu.
>1. Zrób opis modułów lub warstw programu. Opisz ich przeznaczenie (np.
>user interface, poszczególne formy, zestaw funkcji do obsługi bazy danych
>itd).
>2. Opisz złącza między modułami/warstami.
>3. Wybierz z każdego modułu zestaw funkcji/procedur strategicznych i opisz
>ich działanie.
>4. Opisz ew. strukturę bazy danych lub strukturę plików generowanych lub
>czytanych przez program.
>5. Jeśli korzystasz ze standardów (protokoły itp.) podaj je razem z
>oznaczeniami wersji.
>6. Podaj zestaw obcych komponentów (z oznaczeniami wersji i miejscami,
>gdzie są dostępne) potrzebnych do skompilowania całości.
>7. Nie opisuj znaczenia funcji max(a, b) lub tp. Szkoda czasu.
>8. I czółko.
>9. Uzyskaj od swojego upierdliwego klienta pisemny protokół przekazania z
>klauzulą, że źródła oddajesz w całości i od tego momentu nie odpowiadasz
>za nic.
>
Jeśli to ma czemuś służyć to:
1. Dodałbym jeszcze użyte algorytmy - jeśli takie są.
2. Diagram zmian stanów.
3. Diagram przepływu informacji.
Jeśli to baza danych i chcesz dodać do dokumentacji schemat struktury bazy
danych to radzę użyć jakiegoś CASE'a i wykorzystać moduł inżynierii
odwrotnej.
Traptak
--
Wysoka jakość, niskie ceny - http://rubikon.pl
Robert Razniewski
+ historię zmian potencjałów na synapsach programisty :-)
Nie przesadzajmy.
rr