Jakie są style pisania dokumentacji do kodu, projektów itp. (głownie chodzi mi o C#)

Czy możecie nakierować mnie na to w jaki sposób pisać dokumentację do swojego projektu?

Odłóżmy na chwile zagadnienia związane z czystym kodem i pisaniem testów jako "samoaktualizująca się" dokumentacją kodu - bo pytanie dotyczy "tego czegoś" poza tymi zagadnieniami.

Przeszedłem pozytywnie rekrutację, zmieniam profesje na programistę i na rozmowie wstępnej jestem umówiony tak ze "przynoszę" swoje projekty i zaczynam doszlifowywać swój warsztat rozwijając swoje projekty z domeny którą znam, ale nawet zanim to nastąpi mam nauczyć się pisać dokumentację do swojego kodu. Generalnie nakierowano mnie żebym sobie poczytał, o przypadkach użycia, diagramach klas itp. No i poczytałem:

Zacząłem w oparciu o to co wyczytałem tworzyć dokumentację do projektów które mam "przynieść" i rozwijać już na nowym stanowisku, ale wychodzi mi potworek z tego dokumentu.

Mam np.:

Pyt.1. Mam problem z tym do jakiego poziomu szczegółowości schodzić, czy skupiać się tylko na założeniach, wymaganiach i ogólnych przypadkach użycia?

Pyt.2. Czy przypadki użycia rozpisywać wg algorytmu jak to ma działać, czy w odniesieniu do rzeczywistego kodu który to wykonuje, aby "ten ktoś inny" mógł za pomocą tej dokumentacji szybciej wejść w projekt i zorientować się co gdzie jest?

Pyt.3. Jak podejść do miejsc gdzie w projekcie nie ma nic poza planem wdrożenia jakiegoś przypadku użycia, ale już wiadomo że jeżeli zacznę implementować tą funkcjonalność to ona pociągnie za sobą konieczność refaktoryzacji bo na podstawie wcześniejszych wymagań podjąłem błędne decyzje projektowe.

Pyt.4. Jak opisać już zarys co, jak i dlaczego trzeba będzie refakturować? czy tylko w części dotyczącej wdrożenia nowej funkcjonalności która wymusi refaktoring? czy również w innych miejscach obecnie działających ale jeszcze nie przystosowanych do przyjęcia tych kolejnych nowych funkcjonalności?

Pyt.5. Są jakieś ogólne standardy pisania takich dokumentów? można gdzieś do nich trafić /jakiś szablonów/przykładów/ a jeżeli tak to interesowały by mnie takie nie wyidealizowane tylko takie które faktycznie gdzieś u kogoś w firmie są używane (w sensie szukam czegoś praktycznego a nie idealnego/życzeniowego ale nie do wdrożenia w rzeczywistości)

za każdą podpowiedz będę wdzięczny.

tl;dr;

Nie ma żadnego standardu pisania dokumentacji i wszystko zależy od typu projektu i klienta dla którego realizujesz projekt. To że zaczyna ci wychodzić potworek to normalne skoro musisz rozpisywać każde wymaganie na przypadki użycia i je opisywać i nie daj boże robić diagramy klas.

Pyt.5. Są jakieś ogólne standardy pisania takich dokumentów? można gdzieś do nich trafić /jakiś szablonów/przykładów/ a jeżeli tak to interesowały by mnie takie nie wyidealizowane tylko takie które faktycznie gdzieś u kogoś w firmie są używane (w sensie szukam czegoś praktycznego a nie idealnego/życzeniowego ale nie do wdrożenia w rzeczywistości)

Dokumentacja ma więcej niż jedno znaczenie. W zależności od wymagań klienta może być bardzo szczegółowa, albo wysokopoziomowa. Nie ma jednego standardu, który mówi jak należy dokumentować system. Przykładowo aplikacja napisana dla banku, będzie musiała być bardzo szczegółowo udokumentowana, żeby przejść audyty wymagane przepisami prawa i innymi regulacjami, a aplikacja do obsługi online pizzerii już nie, o ile nie przetwarza danych wrażliwych czy krytycznych jak karty kredytowe czy dane osobowe.

Mam problem z tym do jakiego poziomu szczegółowości schodzić, czy skupiać się tylko na założeniach, wymaganiach i ogólnych przypadkach użycia?

J/w zależy od klienta i typu projektu.

Czy przypadki użycia rozpisywać wg algorytmu jak to ma działać, czy w odniesieniu do rzeczywistego kodu który to wykonuje, aby "ten ktoś inny" mógł za pomocą tej dokumentacji szybciej wejść w projekt i zorientować się co gdzie jest?

J/w, zależy od klienta i projektu. W moim obecnym projekcie dla dużego korpo z branży farmaceutycznej, tworzymy rozwiązanie do obsługi badań klinicznych (Clinical Trial Management System) i tam z racji tego, że to jest dziedzina biznesowa podlegająca pod regulacje medyczne i szeroko pojęte GxP to każdy krok aplikacji musi być dokładnie opisany.

Jak podejść do miejsc gdzie w projekcie nie ma nic poza planem wdrożenia jakiegoś przypadku użycia, ale już wiadomo że jeżeli zacznę implementować tą funkcjonalność to ona pociągnie za sobą konieczność refaktoryzacji bo na podstawie wcześniejszych wymagań podjąłem błędne decyzje projektowe.

J/w, zależy od klienta i typu projektu. W aplikacjach podlegających pod GxP każda zmiana musi być oficjalnie udokumentowana i wprowadzona przez formalny Change Request. Zanim trafi do oficjalnej dokumentacji to cała aplikacja musi zostać ponownie przetestowana i zwalidowana przez zespół QA.

Jak opisać już zarys co, jak i dlaczego trzeba będzie refakturować? czy tylko w części dotyczącej wdrożenia nowej funkcjonalności która wymusi refaktoring? czy również w innych miejscach obecnie działających ale jeszcze nie przystosowanych do przyjęcia tych kolejnych nowych funkcjonalności?

J/w, zależy od klienta i projektu. Przykładowo w aplikacjach jak ta o której pisałem wyżej, funkcjonalności które nie istnieją bądź są w fazie koncepcyjnej nie trafiają do oficjalnej dokumentacji. Istnieją sobie w wewnętrznym backlogu projektu.

Dzięki @markone_dev , uszczegóławiajac - projekt i wymagania do dokumentacji. To wszystko jest na potrzeby wewnętrzne firmy. W firmie jest dział programistów którzy robią narzędzia na potrzeby wewnętrzne firmy produkcyjnej. Także celem tej dokumentacji jest, pomoc w wejściu do projektu nowym osobom. Albo przekazanie projektu innej osobie. Chodzi o skrócenie czasu wejścia w ten projekt dzięki dokumentacji.

@Varran: W tej sytuacji to skupiłbym się na opisie funkcjonalnym i niefunkcjonalnym aplikacji. Czyli opisałbym przypadki użycia, procesy biznesowe oraz dlaczego coś zostało zrobione w ten a nie inny sposób. W tym celu możesz zastosować UML-owe use case tables, diagramy aktywności oraz diagramy modułów, żeby pokazać strukturę aplikacji i to w jaki sposób integruje się z innymi rzeczami jak czujniki, maszyny, aplikacje firm trzecich jak SAP czy inne ERP i tak dalej.

Do poziomu diagramu klas czy podobnych jak diagramy E/R opisujących w szczegółach jak kod jest zaimplementowany, jakie są nazwy klas, metod, pól i zmiennych, nazwy tabel i kolumn bym nie schodził bo będzie go bardzo trudno utrzymać z tym co aktualnie jest w kodzie.

Rozumiem że opisy słowne są ok, typu w jakimś viewmodelu wydzielone jest coś do abstrakcji bo.... i pod kątem czegoś tam w przyszłości albo jakiś kontroler ma taką strukturę i żeby go użyci to trzeba to, to i to
i w takiej kolejnosci zrobić?

Varran napisał(a):

Rozumiem że opisy słowne są ok, typu w jakimś viewmodelu wydzielone jest coś do abstrakcji bo.... i pod kątem czegoś tam w przyszłości albo jakiś kontroler ma taką strukturę i żeby go użyci to trzeba to, to i to
i w takiej kolejnosci zrobić?

Nie odpowiem ci bo jest to dość subiektywne i zależy od standardów przyjętych w projekcie. Generalnie dokumentacja powinna odpowiadać na dwa pytania. Jak? i Dlaczego? To jaki poziom szczegółowości zastosować to kwestia umowna. Jedni będą woleli bardziej szczegółowe opisy inni mniej.

Pamiętaj tylko że im bardziej szczegółowe opisy tym trudniej je utrzymać w synchronizacji z tym jak aplikacja działa i co robi bo każda najmniejsza zmiana w kodzie albo logice musi zostać udokumentowana. Dlatego trzeba znaleźć złoty środek.

Varran napisał(a):

Odłóżmy na chwile zagadnienia związane z czystym kodem i pisaniem testów jako "samoaktualizująca się" dokumentacją kodu - bo pytanie dotyczy "tego czegoś" poza tymi zagadnieniami.

No to ja się od razu wypowiem, że na starcie to Cię stawia w przegranej pozycji, a to z prostego powodu: Kod zawsze jest up-to-date, dokumentacja tylko wtedy jest up-to-date jak ktoś ją zaktualizuje. Kod się wiecznie zmienia, powinien się wiecznie zmieniać, więc utrzymywanie takiej dokumentacji to jest ogromny koszt, na który większość nie może sobie pozwolić, i wręcz czasem nie może sobie pozwolić. Jest to piekielny wysiłek, bo praktycznie po każdym commicie musisz wejść do takiej dokumentacji i poprawić jeden lub kilka paragrafów. Nie wiem czy jesteś w stanie wprowadzić jakąkolwiek nietrywialną zmianę, żebyś nie był zmuszony również zaktualizować dokumentacji. Z tego powodu jednak znacznie lepszym podejściem byłoby napisanie kodu jak najprościej jak się da, i napisanie dobrych testów do niego, żeby ciężar dokumentacji zmniejszyć. Nie chodzi tylko o to żeby ją napisać, tylko o to żeby utrzymać ją zgodną z kodem od teraz już po wsze czasy.

Więc zastanów się czy się nie porywasz z motyką na słońce. Być może jesteś od startu skazany na porażkę.

Varran napisał(a):

Przeszedłem pozytywnie rekrutację, zmieniam profesje na programistę i na rozmowie wstępnej jestem umówiony tak ze "przynoszę" swoje projekty i zaczynam doszlifowywać swój warsztat rozwijając swoje projekty z domeny którą znam, ale nawet zanim to nastąpi mam nauczyć się pisać dokumentację do swojego kodu. Generalnie nakierowano mnie żebym sobie poczytał, o przypadkach użycia, diagramach klas itp. No i poczytałem:

Diagramy klas to jest najgorsze co możesz zrobić, ktokolwiek Ci to poradził chce tylko patrzeć jak cierpisz, nie rób tego.

Co do pozostałych rzeczy, to zależy jaką dokumentację chcesz pisać, bo masz dwie do wyboru:

• Albo piszesz dokumentację dla użytkowników Twoich programów (albo bibliotek), i wtedy je musisz pisać z punktu widzenia tego kto ich używa (czyli bez technicznych szczegółów)
• Albo piszesz dokumentację dla przyszłych programistów, i tutaj trud jest znacznie większy bo musisz opisać zarówno wszystkie problemy i funkcjonalności, jak również pomoc której może ktoś potrzebować podczas developowania.
• Jak piszesz dokumentację do biblioteki, to to jest kolejny poziom zagnieżdżenia, bo Twoimi użytkownikami są inni programiści - ale nie ma sensu o tym pisać, bo Ty masz aplikację, nie bibliotekę, prawda?

Więc pytanie którą z nich faktycznie chcesz napisać.

Varran napisał(a):

Zacząłem w oparciu o to co wyczytałem tworzyć dokumentację do projektów które mam "przynieść" i rozwijać już na nowym stanowisku, ale wychodzi mi potworek z tego dokumentu.

Zależy co masz na myśli mówiąc "potworek". Jeśli chodzi Ci o samą objętość, to to jest spodziewane. Nawet proste aplikacje mają bardzo obszerne dokumentacje, i to jest normalne. Jeśli chodzi Ci o to że jest nieuporządkowana, to faktycznie trochę słabo, ale to przychodzi z doświadczeniem.

Pamiętaj że dokumentacja ewoluuje tak samo jak kod. Jeśli napiszesz jakiś rozdział, to jest bardzo prawdopodobne, że zmienisz go jeszcze 30 razy w ciągu życia aplikacji.

Pyt.1. Mam problem z tym do jakiego poziomu szczegółowości schodzić, czy skupiać się tylko na założeniach, wymaganiach i ogólnych przypadkach użycia?

To zależy który typ dokumentacji piszesz, o którym mówiłem wyżej. Jeśli dokumentacja jest dla użytkowników, to nie piszesz nic o kodzie, a jedynie o tym jak używać aplikacji. Co do szczegółów, to chodzi o to żeby było opisane wszystko co można zrobić przy użyciu tej aplikacji. Jeśli piszesz dokumentacje dla programistów którzy mają rozwijać projekt, to musisz opisać wszystko czego może potrzebować programista który właśnie wszedł w Twój projekt.

Pyt.2. Czy przypadki użycia rozpisywać wg algorytmu jak to ma działać, czy w odniesieniu do rzeczywistego kodu który to wykonuje, aby "ten ktoś inny" mógł za pomocą tej dokumentacji szybciej wejść w projekt i zorientować się co gdzie jest?

Jeśli dokumentacja ma być dla programistów, to dobrze jest podlinkować miejsca w kodzie, oraz ewentualnie wkleić przykłady kodu, tylko wtedy musisz pamiętać żeby je zaktualizować jak kod się zmieni.

Pyt.3. Jak podejść do miejsc gdzie w projekcie nie ma nic poza planem wdrożenia jakiegoś przypadku użycia, ale już wiadomo że jeżeli zacznę implementować tą funkcjonalność to ona pociągnie za sobą konieczność refaktoryzacji bo na podstawie wcześniejszych wymagań podjąłem błędne decyzje projektowe.

Najlepsze podejście to byłoby: teraz jest zrefakorować.

Jeśli nie chcesz tego robić, to po prostu opisz to: "Jest plan żeby dodać feature X, ale nie da się go zrobić bez refaktoryzacji", po prostu opisz to jak dla człowieka który wejdzie i będzie chciał to zrobić.

Pyt.4. Jak opisać już zarys co, jak i dlaczego trzeba będzie refakturować? czy tylko w części dotyczącej wdrożenia nowej funkcjonalności która wymusi refaktoring? czy również w innych miejscach obecnie działających ale jeszcze nie przystosowanych do przyjęcia tych kolejnych nowych funkcjonalności?

Również w miejscach obecnie działających.

Pyt.5. Są jakieś ogólne standardy pisania takich dokumentów? można gdzieś do nich trafić /jakiś szablonów/przykładów/ a jeżeli tak to interesowały by mnie takie nie wyidealizowane tylko takie które faktycznie gdzieś u kogoś w firmie są używane (w sensie szukam czegoś praktycznego a nie idealnego/życzeniowego ale nie do wdrożenia w rzeczywistości)

Standardów i szablonów nie ma.

Riddle napisał(a):

Varran napisał(a):

Odłóżmy na chwile zagadnienia związane z czystym kodem i pisaniem testów jako "samoaktualizująca się" dokumentacją kodu - bo pytanie dotyczy "tego czegoś" poza tymi zagadnieniami.

No to ja się od razu wypowiem, że na starcie to Cię stawia w przegranej pozycji, a to z prostego powodu: Kod zawsze jest up-to-date, dokumentacja tylko wtedy jest up-to-date jak ktoś ją zaktualizuje. Kod się wiecznie zmienia, powinien się wiecznie zmieniać, więc utrzymywanie takiej dokumentacji to jest ogromny koszt, na który większość nie może sobie pozwolić, i wręcz czasem nie może sobie pozwolić. Jest to piekielny wysiłek, bo praktycznie po każdym commicie musisz wejść do takiej dokumentacji i poprawić jeden lub kilka paragrafów. Nie wiem czy jesteś w stanie wprowadzić jakąkolwiek nietrywialną zmianę, żebyś nie był zmuszony również zaktualizować dokumentacji. Z tego powodu jednak znacznie lepszym podejściem byłoby napisanie kodu jak najprościej jak się da, i napisanie dobrych testów do niego, żeby ciężar dokumentacji zmniejszyć. Nie chodzi tylko o to żeby ją napisać, tylko o to żeby utrzymać ją zgodną z kodem od teraz już po wsze czasy.

Więc zastanów się czy się nie porywasz z motyką na słońce. Być może jesteś od startu skazany na porażkę.

a moze nie po napisanieu kodu, tylko w trakcie przemyśleń podczas jego pisania, i pisanie dokumentacji może pokazać że kod jest napisane nadmiarowo i niepotrzebnie

Varran napisał(a):

Przeszedłem pozytywnie rekrutację, zmieniam profesje na programistę i na rozmowie wstępnej jestem umówiony tak ze "przynoszę" swoje projekty i zaczynam doszlifowywać swój warsztat rozwijając swoje projekty z domeny którą znam, ale nawet zanim to nastąpi mam nauczyć się pisać dokumentację do swojego kodu. Generalnie nakierowano mnie żebym sobie poczytał, o przypadkach użycia, diagramach klas itp. No i poczytałem:

Diagramy klas to jest najgorsze co możesz zrobić, ktokolwiek Ci to poradził chce tylko patrzeć jak cierpisz, nie rób tego.

Co do pozostałych rzeczy, to zależy jaką dokumentację chcesz pisać, bo masz dwie do wyboru:

• Albo piszesz dokumentację dla użytkowników Twoich programów (albo bibliotek), i wtedy je musisz pisać z punktu widzenia tego kto ich używa (czyli bez technicznych szczegółów)

jak bibliotek to opisujesz wszystkie publicznie dostępne rzeczy, prywatnych nie

• Albo piszesz dokumentację dla przyszłych programistów, i tutaj trud jest znacznie większy bo musisz opisać zarówno wszystkie problemy i funkcjonalności, jak również pomoc której może ktoś potrzebować podczas developowania.

jak dla programistów to dużo załatwiają komentarze przy nagłówkach funkcji i trudniejszych kawałkach bezpośrednio w kodzie

Pyt.2. Czy przypadki użycia rozpisywać wg algorytmu jak to ma działać, czy w odniesieniu do rzeczywistego kodu który to wykonuje, aby "ten ktoś inny" mógł za pomocą tej dokumentacji szybciej wejść w projekt i zorientować się co gdzie jest?

Jeśli dokumentacja ma być dla programistów, to dobrze jest podlinkować miejsca w kodzie, oraz ewentualnie wkleić przykłady kodu, tylko wtedy musisz pamiętać żeby je zaktualizować jak kod się zmieni.

takie coś to jest pierwszy kandydat do /dev/null
programista czyta kod i tam szuka komentarzy

Dodam jeszcze ze diagramy klas oraz diagramy tabel w bazie są wielką pomocą o ile nie są pisane za bardzo formalnie

Miang napisał(a):

• Albo piszesz dokumentację dla przyszłych programistów, i tutaj trud jest znacznie większy bo musisz opisać zarówno wszystkie problemy i funkcjonalności, jak również pomoc której może ktoś potrzebować podczas developowania.

jak dla programistów to dużo załatwiają komentarze przy nagłówkach funkcji i trudniejszych kawałkach bezpośrednio w kodzie

A "Clean code" Pan czytał?

Komentarze w kodzie również stają się out-of-date, podobnie jak dokumentacja.

@Riddle:

Riddle napisał(a):

Varran napisał(a):

Odłóżmy na chwile zagadnienia związane z czystym kodem i pisaniem testów jako "samoaktualizująca się" dokumentacją kodu - bo pytanie dotyczy "tego czegoś" poza tymi zagadnieniami.

No to ja się od razu wypowiem, że na starcie to Cię stawia w przegranej pozycji, a to z prostego powodu: Kod zawsze jest up-to-date, dokumentacja tylko wtedy jest up-to-date jak ktoś ją zaktualizuje. Kod się wiecznie zmienia, powinien się wiecznie zmieniać, więc utrzymywanie takiej dokumentacji to jest ogromny koszt, na który większość nie może sobie pozwolić, i wręcz czasem nie może sobie pozwolić. Jest to piekielny wysiłek, bo praktycznie po każdym commicie musisz wejść do takiej dokumentacji i poprawić jeden lub kilka paragrafów. Nie wiem czy jesteś w stanie wprowadzić jakąkolwiek nietrywialną zmianę, żebyś nie był zmuszony również zaktualizować dokumentacji. Z tego powodu jednak znacznie lepszym podejściem byłoby napisanie kodu jak najprościej jak się da, i napisanie dobrych testów do niego, żeby ciężar dokumentacji zmniejszyć. Nie chodzi tylko o to żeby ją napisać, tylko o to żeby utrzymać ją zgodną z kodem od teraz już po wsze czasy.

Rozumiem to i pisząc o odkładaniu na bok zagadnień związanych z czystym kodem i dokumentowaniem kodu poprzez testy nie miałem na myśli że to złe tylko ten post założyłem po to żeby dowiedzieć się jak to się robi jeszcze inaczej. Już wiem ze to będzie ode mnie wymagane, wiec dobrze z paru źródeł dowiedzieć się jak różni ludzie do tego podchodzą.
Tak naprawdę wszystko mi się ułożyło co i jak mam zrobić czytając dwie odpowiedzi:

@markone_dev

Generalnie dokumentacja powinna odpowiadać na dwa pytania. Jak? i Dlaczego?

oraz:
@markone_dev

W tej sytuacji to skupiłbym się na opisie funkcjonalnym i niefunkcjonalnym aplikacji. Czyli opisałbym przypadki użycia, procesy biznesowe oraz dlaczego coś zostało zrobione w ten a nie inny sposób.

@Riddle:

A "Clean code" Pan czytał?

Oczywiście Panie Riddle ;) że czytałem. Raz gdy tylko wydawało mi się ze już poznałem C# ale niewiele z niej zrozumiałem, potem gdy faktycznie coś praktycznie popisałem i już więcej wyniosłem z tej książki , myślę ze jeszcze parę razy do niej wrócę tak samo jak do "Testów jednostkowych" R.Osherove'a

Komentarze w kodzie również stają się out-of-date, podobnie jak dokumentacja.

Myślę ze jeżeli czytając metodę jak prozę, rozumiem co się po kolei dzieje - to faktycznie komentarze wydają się zbędne.
Tak samo jak test, jeżeli czytając go jak prozę jeżeli rozumiem co się dzieje na etapie przygotowania do testu, wywołania testu i sprawdzania - to to wystarczy.

Disclaimer - w odpowiedzi poniżej pomijam aplikacje dla których dokumentacja jest wymagana przez przepisy prawne i regulacje. Tutaj nie ma nad czym dyskutować.

Jakoś nikt nie narzeka na dokumentację popularnych frameworków i bibliotek. Co więcej, często posiadanie dobrze napisanej i dostępnej dokumentacji jest go albo no-go dla użycia jej w projekcie. To samo się tyczy dokumentacji aplikacji.

Problem jest w tym, że ludzie nie umieją pisać dobrej dokumentacji aplikacji, a biznes nie chce dawać czasu i pieniędzy na jej pisanie/utrzymanie.

Przecież nikt nikomu nie każe używać wszystkich 14 typów diagramów z UML oraz opisywać i rozbijać na atomy każdego przypadku użycia. Czasem wystarczy dobrze napisane ReadMe o czym jest projekt, jak go zbudować i uruchomić wraz z krótkim wiki jaka jest architektura, jak używać API aplikacji czy modułu nad którym pracujemy, jakie mechanizmy uwierzytelniania czy sposoby integracji oferujemy, itd. Do tego można dodać przykład integracji/użycia.

W większych aplikacjach konieczne może się okazać opisanie krytycznych procesów biznesowych, zwłaszcza jak nie mamy jednej aplikacji ale kilka komunikujących się ze sobą.

Myślmy o dokumentacji jak o narzędziu, a nie jak o celu samym w sobie.

markone_dev napisał(a):

Disclaimer - w odpowiedzi poniżej pomijam aplikacje dla których dokumentacja jest wymagana przez przepisy prawne i regulacje. Tutaj nie ma nad czym dyskutować.

Jakoś nikt nie narzeka na dokumentację popularnych frameworków i bibliotek. Co więcej, często posiadanie dobrze napisanej i dostępnej dokumentacji jest go albo no-go dla użycia jej w projekcie. To samo się tyczy dokumentacji aplikacji.

Problem jest w tym, że ludzie nie umieją pisać dobrej dokumentacji aplikacji, a biznes nie chce dawać czasu i pieniędzy na jej pisanie/utrzymanie.

Przecież nikt nikomu nie każe używać wszystkich 14 typów diagramów z UML oraz opisywać i rozbijać na atomy każdego przypadku użycia. Czasem wystarczy dobrze napisane ReadMe o czym jest projekt, jak go zbudować i uruchomić wraz z krótkim wiki jaka jest architektura, jak używać API aplikacji czy modułu nad którym pracujemy, jakie mechanizmy uwierzytelniania czy sposoby integracji oferujemy, itd. Do tego można dodać przykład integracji/użycia.

W większych aplikacjach konieczne może się okazać opisanie krytycznych procesów biznesowych, zwłaszcza jak nie mamy jednej aplikacji ale kilka komunikujących się ze sobą.

Myślmy o dokumentacji jak o narzędziu, a nie jak o celu samym w sobie.

raczje widzę ze przeciwko dokumentacji są kierownicy Janusze

@Miang:

raczje widzę ze przeciwko dokumentacji są kierownicy Janusze

Różnie to bywa. Trzeba by wpierw określić o jakiej dokumentacji mówimy.

Napisanie i utrzymywanie ReadMe z takimi informacjami napisałem w poście wyżej, to powinien być obowiązek programistów. Dokładnie w taki sposób jak to ma miejsce w projektach open source.

Jeżeli mówimy o dokumentowaniu procesów biznesowych i wewnętrznej architektury każdej aplikacji/usługi/modułu to już wymaga to dużego nakładu pracy i trzeba oszacować czy nam się to w ogóle będzie opłacać i nie ma tu powodu do januszowania, bo jeżeli nikt poza nami nie jest odbiorcą dokumentacji to faktycznie nie ma sensu jej tworzyć.

To kolejny aspekt, który trzeba rozważyć "kto jest odbiorcą dokumentacji" i pod niego dobierać poziom jej szczegółowości.

Miang napisał(a):

raczje widzę ze przeciwko dokumentacji są kierownicy Janusze

Wystarczy zrobić krok wstecz, i zastanowić się "po co to robić?". No bo ogólnie celem dokumentacji jest to żeby, po pierwsze ktoś mógł zapoznać się z projektem i wejść do niego; dwa znaleźć informacje które mogły mu umknać; czyli ostatecznie żeby usprawnić pracę z projektem.

W podobnym celu pisze się czysty kod, małe klasy, robi refaktor i pisze testy.

Pytanie tylko - które z tych podejść jest lepsze; czy w ogóle jest lepsze i może te podejścia się uzupełniają (ja wiem które bym obstawił).

Zazwyczaj dokumentuje się kontrakty(REST API, interfejsy w fasadach itd.). W bardziej skomplikowanych projektach dokumentuje się, ADR(architecture decision record) tj decyzje architektoniczne czemu na tamten moment podjęło się taką decyzję a nie inną. Max co się czasami sprawdza w systemach gdzie masz dziesiątki pod-projektów są HLD(High-Level Design) aby udokumentować co z czym gada i ew po co.

Dokumentowanie szczegółowej implementacji na poziomie większym niż wyjaśnienie nieoczywistych optymalizacji/kroków jest mocno zbędne a i tak się z czasem pewnie przedawni.

A co do rodzajów dokumentacji to to jest dobra grafika :P Dodałbym od siebie, że czasami w projektach które mają problem z ogarniętym product ownerem zdarza mi się pisać RFC.

@Riddle:

Kod się wiecznie zmienia, powinien się wiecznie zmieniać, więc utrzymywanie takiej dokumentacji to jest ogromny koszt, na który większość nie może sobie pozwolić

Miałem "przyjemność+ przejmować kod po dostawcy, który naopowiadał tego klientowi, a klient był za leniwy by wymagać jakiejś dokumentacji. I nie mówię o szczegółowo rozpisanych use-cases - wiem na jakim świecie żyjemy. Ale parę stron opisujące koncepcje i pewne decyzje architektoniczne, czy nawet już implementacyjne oszczędziłyby masy problemów. A tak to było naprawdę dużo zagrań z repertuaru archeologii w stylu Indiana Jonesa, żeby ustalić po co są niektóre moduły, fragmenty kodu, etc.

Ogólnie odnośnie pisania dokumentacji, to najważniejsze pytania na jakie powinna odpowiadać - dla kogo ona jest i co ma z niej uzyskać. Co innego dokumentacja utrzymaniowa, co innego dla użytkowników biznesowych, co innego dla devów i testerów. Z założenia powinna być pisana w taki sposób, żeby wczuć się w rolę danego człowieka i zastanowić, czego może potrzebować podchodząc do tego dokumentu. Bo potrzeby będą inne w różnych rolach, będą wymagały też różnego poziomu szczegółowości.

brzezmac napisał(a):

@Riddle:

Kod się wiecznie zmienia, powinien się wiecznie zmieniać, więc utrzymywanie takiej dokumentacji to jest ogromny koszt, na który większość nie może sobie pozwolić

Miałem "przyjemność+ przejmować kod po dostawcy, który naopowiadał tego klientowi, a klient był za leniwy by wymagać jakiejś dokumentacji. I nie mówię o szczegółowo rozpisanych use-cases - wiem na jakim świecie żyjemy. Ale parę stron opisujące koncepcje i pewne decyzje architektoniczne, czy nawet już implementacyjne oszczędziłyby masy problemów. A tak to było naprawdę dużo zagrań z repertuaru archeologii w stylu Indiana Jonesa, żeby ustalić po co są niektóre moduły, fragmenty kodu, etc.

Ogólnie odnośnie pisania dokumentacji, to najważniejsze pytania na jakie powinna odpowiadać - dla kogo ona jest i co ma z niej uzyskać. Co innego dokumentacja utrzymaniowa, co innego dla użytkowników biznesowych, co innego dla devów i testerów. Z założenia powinna być pisana w taki sposób, żeby wczuć się w rolę danego człowieka i zastanowić, czego może potrzebować podchodząc do tego dokumentu. Bo potrzeby będą inne w różnych rolach, będą wymagały też różnego poziomu szczegółowości.

Okej, to powiem inaczej:

1. Najgorsze co może być: brak dokumentacji oraz nieczytelny kod
2. Lepiej - ktoś Ci opowie o aplikacji
3. Bardzo dobrze - mieć dobrze napisaną dokumentację
4. Superowo - mieć tak czysto napisaną aplikację, że można ją w pełni zrozumieć nawet bez czytania dokumentacji (mogłoby jej wtedy w ogóle nie być).

Jeśli jesteś w punkcie 2., to posiadanie dokumentacji jest wartością dodatnią. Jeśli jesteś w punkcie 4., to dokumentacja jest krokiem wstecz.

i takie podejście kończy się na dodawaniu nadmiarowego kodu który ma komentować poprzez samą swoja obecność

Miang napisał(a):

i takie podejście kończy się na dodawaniu nadmiarowego kodu który ma komentować poprzez samą swoja obecność

Otóż wręcz przeciwnie. Nie chodzi o to, żeby pisać kod tak żeby był dokumentacją (to nie jest cel sam w sobie), chodzi o napisanie czystego kodu, który jest prosty, krótki, i nie jest przesadnie skomplikowany - tak napisany kod, będzie tak czytelny, że nie będzie wymagał dodatkowego opisu.

Serio, poświęć dwa dni na przeczytanie tej książki: https://thixalongmy.haugiang.gov.vn/media/1175/clean_code.pdf Sporo Ci się rozjaśni, i może przestaniesz wtedy wygadywać takie farmazony.

Riddle napisał(a):

Otóż wręcz przeciwnie. Nie chodzi o to, żeby pisać kod tak żeby był dokumentacją (to nie jest cel sam w sobie), chodzi o napisanie czystego kodu, który jest prosty, krótki, i nie jest przesadnie skomplikowany - tak napisany kod, będzie tak czytelny, że nie będzie wymagał dodatkowego opisu.

Bzdety.

Nikt nie będzie czytał kodu w celu użycia jakiejś biblioteki czy aplikacji. Niezbędna jest dokumentacja dokładnie opisująca sposób konfiguracji, wywołania, a także ograniczenia i wymagania danego softu.

Jeśli autor softu nie potrafi dostarczyć takiej dokumentacji, to oznacza, że nie wie, co zrobił, więc cały jego czysty kod jest g**no wart.

somekind napisał(a):

Riddle napisał(a):

Otóż wręcz przeciwnie. Nie chodzi o to, żeby pisać kod tak żeby był dokumentacją (to nie jest cel sam w sobie), chodzi o napisanie czystego kodu, który jest prosty, krótki, i nie jest przesadnie skomplikowany - tak napisany kod, będzie tak czytelny, że nie będzie wymagał dodatkowego opisu.

Bzdety.

Nikt nie będzie czytał kodu w celu użycia jakiejś biblioteki czy aplikacji. Niezbędna jest dokumentacja dokładnie opisująca sposób konfiguracji, wywołania, a także ograniczenia i wymagania danego softu.

Jeśli autor softu nie potrafi dostarczyć takiej dokumentacji, to oznacza, że nie wie, co zrobił, więc cały jego czysty kod jest g**no wart.

Okej, to może podrasuję moją listę z postu wyżej.

1. Najgorsze co może być: brak dokumentacji oraz nieczytelny kod
2. Lepiej - ktoś Ci opowie o aplikacji
3. Dobrze - mieć napisaną dokumentację, która nie jest najlepsza i pod wieloma aspektami jest płytka, uboga, i out of date
4. Bardzo dobrze - mieć tak czysto napisaną aplikację, że taka słaba dokumentacja jest całkowicie niepotrzebna.
5. Super dobrze - mieć bardzo bogatą dokumentacje, która zawiera informacje których nie ma bezpośrednio w kodzie, jest cross-referenced, jest wersjonowana, zawiera szczegóły na odpowiednim poziomie, spis treści, oraz jest dobrym źródłem.

@somekind: pisał jak rozumiem o punkcie 5. i zgadzam się że to jest bardzo dobre wyjście (tylko nie każdy taką dokumentacje potrafi napisać, stworzenie jej też nie jest tanie, i wymaga pracy, rewizji, aktualizacji, często napisanie dobrej dokumentacji zajmuje podobną ilośc czasu co wytworzenie oprogramowania). Ja mówiłem o punkcie 4., że jeśli masz mieć dokumentację taką jak większość firm robi (czyli "pole user - holds the current user"), to bez sensu ją robić. Większość firm stosuje podejście 1. albo 3.

Riddle napisał(a):

nie każdy taką dokumentacje potrafi napisać, stworzenie jej też nie jest tanie, i wymaga pracy, rewizji, aktualizacji, często napisanie dobrej dokumentacji zajmuje podobną ilośc czasu co wytworzenie oprogramowania).

No cóż, praca programisty to nie tylko klepanie kodu.

Ja mówiłem o punkcie 4., że jeśli masz mieć dokumentację taką jak większość firm robi (czyli "pole user - holds the current user"), to bez sensu ją robić.

Tak, tu się zgadzam. Tylko jak dla mnie to nie jest dokumentacja - dokumentacja mówi jak używać softu, nie co w nim jest.

somekind napisał(a):

Ja mówiłem o punkcie 4., że jeśli masz mieć dokumentację taką jak większość firm robi (czyli "pole user - holds the current user"), to bez sensu ją robić.

Tak, tu się zgadzam. Tylko jak dla mnie to nie jest dokumentacja - dokumentacja mówi jak używać softu, nie co w nim jest.

No właśnie, wszystko się sprowadza do tego co rozumiesz pod słowem "dokumentacja". Jeśli ta z punktu 5., to faktycznie dobrze ją mieć. Jeśli ta z punktu 3., to lepiej nie mieć i wyczyścić kod.