GoldenLine
Zaloguj się
Hubert Wesołowski

Hubert Wesołowski Człowiek od krycia
dachów podczas
deszczu (mokrej
roboty).

Temat: pisanie dokumentacji, doswiadczenia/przemyslenia/uwagi

Witam,
zainspirowany sąsiednim wątkiem postanowiłem stworzyć własny do dyskusji natury ogólnej.
Interesuje mnie Wasze podejście i doświadczenia z dokumentowaniem kodu (proszę nie pisać o manualach i instrukcjach gdzie kliknąć żeby..., chodzi o dokumentacje dla programistów mających rozwijać dalej dany projekt).
Wiem: temat rzeka...
Moje doświadczenia z różnymi sposobami dokumentowania:

- dokumentacja tworzona na bieżąco.
Wady:
prawie nigdy nie dotyczy aktualnej wersji kodu, jest zawsze do tyłu - projekty się zmieniają, tego nie unikniemy - na zmianę doku często nie ma czasu/chęci/motywacji.
Zalety:
czas poświęcany dokumentacji nie jest mocno widoczny dla przełożonych, dzięki temu nie ma pokusy zabrania go. Jesteśmy świeżutko po napisaniu kodu - najlepszy czas na udokumentowane go, czasem pisanie dokumentacji pozwala na refleksję i dobry refactoring. Co myślicie o pomyśle dokumentowania tylko nieswojego kodu? Przy okazji mamy koleżeńską inspekcję kodu oraz załatwione zastępstwo.

- dokumentacja tworzona po ukończeniu projektu.
Wady:
pewne rzeczy były pisane pół roku albo i rok temu... pokusa zabrania tego czasu przez przełożonych (przecież bez dokumentacji też działa, a są inne pilniejsze rzeczy które będą zarabiać $...). Dłuższe pisanie dokumentacji źle wpływa na programistów ;-).
Zalety:
dokumentacja zawsze opisuje aktualną wersję kodu.

- "brak dokumentacji", czyli samokumentujący się kod
Zalety:
powstaje na bieżąco, dotyczy aktualnej wersji kodu, nie ma możliwości zabrania czasu przeznaczonego na dokumentację.
Wady:
rezygnacja z eleganckich rozwiązań na rzecz rozwiązań czytelnych jest traktowana na (+) - skomplikowane, wielopoziomowe modele abstrakcji nie są raczej mile widziane itp., długaśne nazwy metod i atrybutów, dbanie o nieskomplikowany przepływ sterowania.


Mi osobiście najbliżej do 3 opcji, chociaż czasem warto popełnić coś złożonego jeśli poprze się to odpowiednim diagramem, ale to raczej "od święta". Na co dzień staram się pisać prosto, tak aby osoba przejmująca po mnie kod mająca pojęcie o szkielecie framework'a była w stanie łatwo prześledzić działanie kodu. Minusem jest to, że często nie da się wydzielić całej odpowiedzialności do poszczególnych modeli - niejako końce (czy raczej początki) wszystkich nitkek staram się skupić w jednym miejscu. No ale jak to w życiu: coś za coś :-).

Jestem ciekaw jak wygląda to w innych projektach.

Pozdrawiam,
h.
Link do wypowiedziLink
Stanisław P.

Stanisław P. Software designer

Temat: pisanie dokumentacji, doswiadczenia/przemyslenia/uwagi

Hubert Wesołowski:
- "brak dokumentacji", czyli samokumentujący się kod
^^ to
Wady:
rezygnacja z eleganckich rozwiązań na rzecz rozwiązań czytelnych jest traktowana na (+) - skomplikowane, wielopoziomowe modele abstrakcji nie są raczej mile widziane itp., długaśne nazwy metod i atrybutów, dbanie o nieskomplikowany przepływ sterowania.
Trochę to dziwnie brzmi... Czy znasz przykłady eleganckich rozwiązań które są mniej czytelne od innych? To by mnie zaskoczyło.
Co do długich nazw... wewnątrz klas nie są potrzebne. Problem nazw klas rozwiązują namespace'y.
Co do "dbanie o nieskomplikowany przepływ sterowania" - to wada? Serio?

Nie we wszystkich językach da się stosować dosłownie, ale polecam poczytać: http://en.wikipedia.org/wiki/Literate_programming

Co do dokumentacji dla innych programistów... testy są bardzo dobrą dokumentacją.Stanisław Pitucha edytował(a) ten post dnia 23.09.10 o godzinie 23:32
Link do wypowiedziLink

konto usunięte

Temat: pisanie dokumentacji, doswiadczenia/przemyslenia/uwagi

U mnie - opcja 1, z kilkoma wyjątkami gdy po prostu bawię się kodem.
Na moje szczęście - używane przeze mnie IDE pięknie wspiera phpDoc'a, wystarczy nad funkcją metodą napisać /** i enter - potem tylko uzupełnić.

Czasem też opcja 2 - jak mam za dużo czasu, to sobie przeglądam i uzupełniam.Michał Wachowski edytował(a) ten post dnia 24.09.10 o godzinie 00:38
Link do wypowiedziLink
Hubert Wesołowski

Hubert Wesołowski Człowiek od krycia
dachów podczas
deszczu (mokrej
roboty).

Temat: pisanie dokumentacji, doswiadczenia/przemyslenia/uwagi

Tak, np. wielokrotne dziedziczenie - bez diagramów klas raczej ciężko to ogarnąć - śledzenie zwykle zaczynasz od kontrolera (kliknąłeś coś na stronie i chcesz się dowiedzieć co się stało) i teraz się zaczyna: 1 klasa, 2, 3... czasem trzeba kupę kodu przejrzeć zanim dojdziesz co i jak. Głównie właśnie przez skomplikowany przepływ sterowania. Oczywiście takie rozwiązanie ma też sporo plusów, jednak "zewnętrzna" dokumentacja staje się tu elementem niezbędnym aby minusy nie skasowały nam plusów.

Długie nazwy są potrzebne również wewn. klas. A właściwie to nazwy metod mówiące co one robią, jakoś tak się składa, że są zazwyczaj długie :). Chyba, że nie zależy Ci na dokumentowaniu tych metod (podejście mocno niezalecane ;-) ).

Nieskomplikowany przepływ sterowania nie jest oczywiście wadą sam w sobie, ale żeby go osiągnąć trzeba się często zgodzić "brzydkie rzeczy".

Literate programming - nigdy nie miałem okazji bliżej się zapoznać, ale nazwisko twórcy to prawdziwa marka - w TeXu się zakochałem, więc kto wie :)...

Co masz na myśli pisząc "testy"? Jednostkowe, czy coś innego?
Link do wypowiedziLink
Wojciech Soczyński

Wojciech Soczyński Programista
eksplorator -
blog.wsoczynski.pl

Temat: pisanie dokumentacji, doswiadczenia/przemyslenia/uwagi

Hubert Wesołowski:
Tak, np. wielokrotne dziedziczenie - bez diagramów klas raczej ciężko to ogarnąć - śledzenie zwykle zaczynasz od kontrolera (kliknąłeś coś na stronie i chcesz się dowiedzieć co się stało) i teraz się zaczyna: 1 klasa, 2, 3... czasem trzeba kupę kodu przejrzeć zanim dojdziesz co i jak. Głównie właśnie przez skomplikowany przepływ sterowania. Oczywiście takie rozwiązanie ma też sporo plusów, jednak "zewnętrzna" dokumentacja staje się tu elementem niezbędnym aby minusy nie skasowały nam plusów.

Długie nazwy są potrzebne również wewn. klas. A właściwie to nazwy metod mówiące co one robią, jakoś tak się składa, że są zazwyczaj długie :). Chyba, że nie zależy Ci na dokumentowaniu tych metod (podejście mocno niezalecane ;-) ).

Nieskomplikowany przepływ sterowania nie jest oczywiście wadą sam w sobie, ale żeby go osiągnąć trzeba się często zgodzić "brzydkie rzeczy".

Literate programming - nigdy nie miałem okazji bliżej się zapoznać, ale nazwisko twórcy to prawdziwa marka - w TeXu się zakochałem, więc kto wie :)...

Co masz na myśli pisząc "testy"? Jednostkowe, czy coś innego?

Moim zdaniem po to są komentarze i phpDoc żeby opisywać co funkcja robi. Poza tym długie nazwy metod są ciężkie do zapamiętania i niepraktyczne przy wpisywaniu. Dlatego moim zdaniem, nazwa funkcji powinna zawierać tylko absolutne minimum informacji - meritum, które mówi nam co robi, powinna być krótka i treściwa. Co do skomplikowanego przepływu sterowania - moim zdaniem wystarczy trzymać się prostej zasady, opisanej już milion razy - funkcja/metoda powinna mieć jasno określone argumenty wejściowe i wyjściowe, dzięki temu, gdy nawet mamy skomplikowany przepływ sterowania, możemy prześledzić jak ono przebiega. Co do wielokrotnego dziedziczenia - dlatego też zaleca się stosować kompozycje ponad dziedziczenie - ułatwia połapanie się w całości i abstrakcje.
Link do wypowiedziLink

konto usunięte

Temat: pisanie dokumentacji, doswiadczenia/przemyslenia/uwagi

??? tylko po co tworzyc drugi taki sam temat ???
Link do wypowiedziLink

konto usunięte

Temat: pisanie dokumentacji, doswiadczenia/przemyslenia/uwagi

Ja u siebie w kodzie, nie analizuje linijka po linijce kodu, w pierwszym akapicie wstawiam ludzką nazwę funkcji, w drugim z goła co robi, a reszta to standardowy phpDoc, ale takie kosmetyczne ( bo owe dokumentowanie kodu nim dla mnie jest ) zmiany wprowadzam chaotycznie, tzn tam gdzie mi się chce i jak mam na to czas.
Nie będziemy przecież dokumentować akcji w kontrolerze?

A w pracy? Na bieżąco.

Z wyrazami szacunku,
Przemysław Czekaj.
Link do wypowiedziLink
Adam Bąk

Adam Bąk Programista

Temat: pisanie dokumentacji, doswiadczenia/przemyslenia/uwagi

Apropo tego tematu, ja jeszcze dokumentacji nie pisałem ale napewno nadejdzie taki czas że będzie trzeba.

Moje pytanie jest następujące:

Czy przy pisaniu dokumentacji robicie diagramy itp, chodzi mi tu np. o UML, na studiach tego wymagają ale jak jest w praktyce ?? Czy przy większych projektach robicie to ?? Szczerze powiem że UML mi się podobał, ale czy jest niezbędny w projektach portali itp ??
Link do wypowiedziLink
Dominik Marczuk

Dominik Marczuk Remote Team Lead w
Sonalake

Temat: pisanie dokumentacji, doswiadczenia/przemyslenia/uwagi

Kiedy piszę kod PHP, najczęściej komentuję tylko rzeczy potencjalnie niezrozumiałe. Staram się pisać czytelny kod, stosować znaczące nazwy funkcji itd. Czasem nie wychodzi ;).

Teraz robię w PHP większe projekty dla dużego klienta i muszę wszystko dokumentować. Zwykle nie jest większym problemem Dodanie komentarza /**...*/ przed nazwą funkcji, zajmuje to chwilkę i rzadko potem cokolwiek się zmienia.

Inną sytuację mam w przypadku średnio pasującym do tej grupy - C i/lub C++. Dokumentuję dopiero po napisaniu kodu. Właśnie teraz mam na głowie dokumentację dość obszernego frameworka napisanego rok temu. Większość jest gotowa, ale rodzi się to w bólach, bo zupełnie nie pamiętam o czym piszę :D.Dominik Marczuk edytował(a) ten post dnia 25.09.10 o godzinie 17:16
Link do wypowiedziLink
Wojciech Soczyński

Wojciech Soczyński Programista
eksplorator -
blog.wsoczynski.pl

Temat: pisanie dokumentacji, doswiadczenia/przemyslenia/uwagi

Adam Bąk:
Apropo tego tematu, ja jeszcze dokumentacji nie pisałem ale napewno nadejdzie taki czas że będzie trzeba.

Moje pytanie jest następujące:

Czy przy pisaniu dokumentacji robicie diagramy itp, chodzi mi tu np. o UML, na studiach tego wymagają ale jak jest w praktyce ?? Czy przy większych projektach robicie to ?? Szczerze powiem że UML mi się podobał, ale czy jest niezbędny w projektach portali itp ??
Zależy na jakich studiach, bo na AGH drugiej (pod względem poziomu) uczelni technicznej w polsce i 600-którejś tam na świecie nie wymagają. UML warto stosować w skomplikowanych zagadnieniach, jak mamy napisać aplikację, która składa się z 5 ciu klas to moim zdaniem bez sensu jest bawić się w UML-a. Poza tym UML raczej tworzy się przed napisaniem jakiegokolwiek kodu - pokazuje on projekt systemu i na podstawie tego koduje, później takie diagramy można umieścić w dokumentacji...
Link do wypowiedziLink
Hubert Wesołowski

Hubert Wesołowski Człowiek od krycia
dachów podczas
deszczu (mokrej
roboty).

Temat: pisanie dokumentacji, doswiadczenia/przemyslenia/uwagi

@Andrzej: zdecydowanie nie taki sam. nie pytam o to jak udokumentowac istniejacy kod, tylko o doswiadczenia z pisaniem dokumentacji.
po co tworzyc? zeby nie pisac nie na temat w Twoim watku :).
Link do wypowiedziLink
« Wróć do tematów
Odpowiedz

Podobne tematy


Następna dyskusja:

Pisanie dokumentacji...




Wyślij zaproszenie do
Anuluj