On 10/12/2011 22:24, Roman W wrote:
> On Dec 10, 9:34 pm, Andrzej Jarzabek<a...@g...com>
>>
>> Jest trochę taki problem, że jak dokumentacja opisuje rzeczy niezgodne z
>> faktyczną rzeczywistością, to się na niej czas traci dwa razy: raz, jak
>> się ją pisze, drugi raz, jak się próbuje z niej skorzystać.
>
> Z regulay mozna wyodrebnic "rdzen" funkcjonalnosci, ktory sie raczej
> nie zmieni, i przynajmniej ten udokumentowac.

Niewątpliwie, jednak nie zawsze to jest potrzebne.

Oczywiście, że wiele rzeczy dokumentować trzeba. Dla produktu musi
powstać dokumentacja dla użytkownika końcowego, biblioteki czy inne
komponenty powinny mieć udokumentowane API, a wszystkie decyzje,
ustalenia i wnioski dotyczące funkcjonalności powinny być dokumentowane
na bieżąco. I przecież w Agile się tego nie kwestionuje. Przede
wszystkim odrzuca się tworzenie dokumentów, na podstawwie których
tworzony jest program: dokumentacji wymagań i "dokumentu projektowego"
czyli opisania całości struktury i jednostek kodu przed rozpoczęciem
implementacji. W dalszej kolejności odrzuca się w ogóle potrzebę
utrzymywania dokumentacji projektu kodu, nawet jeśli nie jest tworzony z
góry.

>> No i oczywiście rozwiązania agile nie polegają na tym, że nie
>> masz dokumentacji i tyle. Masz mniej dokumentacji niż w niektórych
>> innych rozwiązaniach, ale zamiast dokumentacji masz coś innego.
>
> Co? Testow jednostkowych nie uznaje za dokumentacje.

Dobrze napisane testy jednoostkowe mogą stanowić część dokumentacji
kodu, ale przede wszystkim robi się tak, że zamiast stworzenia na
początek dokumentu wymagań, masz w zespole ludzi, którzy rozumieją te
wymagania na tyle, że mogliby taki dokument napisać, i masz człowieka,
który na bieżąco może podejmować decyzje jak program ma działać, co ma w
nim być, czego być nie ma, co można uprościć i tak dalej.

W kwestii opisu projektu kodu, pierwszą zasadą jest czytelność. Ogólnie
jeśli coś jest nieoczywiste tak, że należałoby to udokumentować, to w
pierwszej kolejności rozważa się, czy nie możnaby tego jednak uczynić
oczywistym. Tak, owszem, czasem się nie da, i od tego masz różne inne
techniki, jak asercje, design by contract czy właśnie różne testy.
Odnośnie tego, unit testy mogą i powinny być dokumentacją projektu kodu,
ale muszą w tym celu być odpowiednio napisane - nie tylko tak, żeby
rzeczywiście testować daną funkcjonalność, ale też tak, żeby w
maksymalnie czytelny sposób wyrażać to, co mają testować. Często
wprowadza się deklaratywny styl kodu testującego, nawet tworząc sweg
rodzaju "domain specific languages" do tego. Jest niezła książka
"Growing Object Oriented Software Guided By Tests" Freemana i Pryce'a,
która pokazuje jak można to zrobić w Javie.

Te same zasady można też rozciągnąć na część dokumentacji wymagań,
stosując tzw. Acceptance Test Driven Development. Tam nie dokumentuje
się jednostek kodu, ale cały system, poprzez tworzenie testów
operujących na zewnętrznych interfejsach. Tu wręcz wymaga się tego, żeby
te testy były wyrażony w sposób jak najbardziej zbliżony do domeny
biznesowej, tak żeby nie-programista (np. przedstawiciel klienta) mógł
czytać taki kod i potwierdzić, że warunki i oczekiwane zachowanie
systemu wyrażone są prawidłowo.

Oczywiście to wszystko nie wyczerpuje sytuacji, gdzie potrzebna jest
dokumentacja w klasycznej postaci (dokumentu), i przecież z agile i
dokumentacją nie chodzi o zaprzeczenie tego faktu, czy o religijne nie
tworzenie dokumentacji tam, gdzie trzeba ją stworzyć, tylko w tym
przypadku o konstatację, że zazwyczaj te alternatywne sposoby sprawdzają
się lepiej od tworzenia z góry i potem utrzymywania dokumentu.