Dokumentacja kodu Najpierw? [Zamknięte]

Czy ktoś kiedykolwiek próbował najpierw utworzyć pełną dokumentację kodu, a dopiero potem napisał kod? Myślałem o tym wcześniej, ponieważ myślałem, że pomogłoby to napisać konkretny interfejs i upewniłem się, że twój początkowy projekt nie został zmieniony, zmuszając cię do zastanowienia się nad interakcją klas. Czy to dobry pomysł? Czy ktoś tego próbował? Łokieć

Tak.

Sprawia, że ​​myślisz o tym, co dokładnie powinien zrobić Twój kod . Chodzi o to, że możesz zacząć od dowolnej części kodu i dokładnie wiedzieć, co należy zrobić, aby ukończyć ten moduł.

Łatwiej jest też naprawić coś na tablicy kreślarskiej niż w IDE.

Istnieją dwa sposoby myślenia na ten temat:

1) Dokumentacja jak w dokumentach Word, Wiki itp. Z definicji nie możesz mieć pełnej dokumentacji kodu, ponieważ nie masz kodu do udokumentowania. Możesz najpierw spróbować udokumentować projekt, założenia, interfejsy i kontrakty na wysokim poziomie.

2) Dokumentacja jako testy wykonywalne. Istnieje szkoła myślenia, która stwierdza, że ​​wykonalne testy jednostkowe są najlepszą dokumentacją. Ta szkoła myślenia zaleca także tego rodzaju dokumentację przed napisaniem kodu (TDD). Jednocześnie od samego początku nie piszesz wszystkich testów dla całego systemu. Najpierw rozkładasz je według przypadków użycia, a następnie wykonujesz testy i kodujesz według przypadków użycia.

Zaczynając od dokumentacji, jest klasyczny model wodospadu i ma wszystkie pułapki związane z tym modelem. Ogólnie rzecz biorąc, im więcej dokumentujesz, tym więcej musisz zaktualizować, gdy zmienią się wymagania. Jedną z korzyści płynących z rozpoczynania pracy z dokumentacją użytkownika jest możliwość wcześniejszego uzyskania informacji zwrotnej (a co za tym idzie zmian). Ale doświadczenie pokazuje, że większość ludzi źle radzi sobie z mentalnym mapowaniem dokumentacji na działania. Zamiast tego używamy prototypów, które pozwalają ludziom faktycznie korzystać z oprogramowania i przekazywać opinie w ten sposób.

Jedną z odmian „najpierw dokumentacji” jest umiejętne programowanie . Zacznij od napisania opisu tego, co program zrobi z perspektywy programisty. Udoskonalaj to, aż się skompiluje. Voila, piśmienny program.

Osobiście uważam, że lepiej jest używać diagramów (takich jak UML) do prostego modelowania, aby pokazać przepływ rzeczy. Jest to o wiele szybsze niż dokumentowanie rzeczy słowami, a jeśli zrobione dobrze, może być tak samo opisowe. Wahałbym się jednak przed zrobieniem pełnej dokumentacji, ponieważ osobiście nigdy nie miałem projektu, nad którym pracowałem, który nie zmienił się podczas programowania.

EDYCJA: Niektóre dokumenty powinny być sporządzane podczas długiej pracy. Ułatwia to później wykonanie pełnej dokumentacji.

Joshua Bloch omawia ten punkt w swoim wywiadzie dla książki „Coders at Work”.

W przeciwieństwie do bardziej ortodoksyjnych i akademickich poglądów, radzi coś do melodii twoich myśli (może sam tam to przeczytałeś?): Że przed napisaniem dokumentacji musisz zrozumieć, czego chcesz od systemu i uzyskać bardziej „realne” „uczucie. W tym celu zaprojektowałby część interfejsów i kod klienta, który ich używa.

Najważniejszą rzeczą jest wiedzieć, co próbujesz zbudować: jaki problem próbujesz rozwiązać. Ważności analizy wymagań nie można przecenić. Są ludzie, którzy myślą: „Och, tak, analiza wymagań; idziesz do swojego klienta, mówisz: „Czego potrzebujesz?” Mówi ci i gotowe.

Nic nie może być dalej od prawdy. To nie tylko negocjacja, ale proces zrozumienia. Wielu klientów nie powie Ci o problemie; powie ci rozwiązanie. Klient może powiedzieć na przykład: „Potrzebuję, abyś dodał obsługę następujących 17 atrybutów do tego systemu. Następnie musisz zapytać: „Dlaczego? Co zamierzasz zrobić z systemem? Jak się spodziewasz, że będzie ewoluować? ”I tak dalej. Poruszasz się do przodu i do tyłu, dopóki nie zorientujesz się, czego naprawdę potrzebuje klient. Są to przypadki użycia.

Najważniejsze, co możesz zrobić na tym etapie, to wymyślenie dobrego zestawu przypadków użycia. Gdy to zrobisz, uzyskasz punkt odniesienia, na podstawie którego możesz zmierzyć każde możliwe rozwiązanie. Jest OK, jeśli spędzasz dużo czasu na zbliżeniu go do racji, ponieważ jeśli pomylisz się, już nie żyjesz. Reszta tego procesu będzie ćwiczeniem na próżno.

Najgorszą rzeczą, jaką możesz zrobić - i widziałem, że tak się dzieje - jest to, że dostajesz grupę inteligentnych facetów do pokoju na sześć miesięcy i piszesz 247- stronicową specyfikację systemu, zanim naprawdę zrozumieją, co to jest. próbuje zbudować. Ponieważ po sześciu miesiącach będą mieli bardzo precyzyjnie określony system, który może być bezużyteczny. I często mówią: „Zainwestowaliśmy tyle w specyfikację, że musimy ją zbudować”. Tworzą więc bezużyteczny system i nigdy się nie przyzwyczaja. I to jest okropne. Jeśli nie masz przypadków użycia, budujesz to, a następnie próbujesz zrobić coś bardzo prostego i zdajesz sobie sprawę, że: „O rany, robienie czegoś bardzo prostego, na przykład wzięcie dokumentu XML i wydrukowanie go, wymaga stron na stronach płyty głównej kod." I to jest okropne.

- Joshua Bloch, z wywiadu w „ Coders at Work: Reflections on the Craft of Programming ” Petera Seibela

Jeśli już myślisz w ten sposób, dobrze byłoby, gdybyś mógł przeczytać książkę i przeczytać cały wywiad. Jak powiedziałem, zawsze jest bardzo pouczający.

Niektórzy ludzie nawet idą dalej i twierdzą, że firma powinna całkowicie działać wstecz, więc

1. Napisz komunikat prasowy
2. Napisz FAQ
3. Określ zadowolenie klienta
4. Napisz instrukcję obsługi
5. Rozpocznij programowanie

Zobacz http://www.allthingsdistribut.com.com/11/working_backwards.html

Pisanie kompletny pierwszy dokumentację kodu jest chyba przesadą i nieco przypominający metodologii wodospadu. Przekonałem się jednak, że bardziej pragmatyczne podejście polega na napisaniu README w pierwszej kolejności. Dlatego:

README nie dokumentuje każdego szczegółu twojego projektu. Zamiast tego zazwyczaj zawiera następujące informacje:

1. Opis : krótka „skala sprzedaży”. Powiedz czytelnikowi, dlaczego powinni kontynuować czytanie.
2. Szybkie przykłady : krótkie fragmenty kodu lub zrzuty ekranu na poparcie opisu.
3. Szybki start : jak zacząć, instrukcje instalacji i więcej przykładów.
4. Dalsza dokumentacja : linki do pełnych dokumentów i więcej informacji.
5. Organizacja projektu : kim są autorzy, jak wnosić wkład, jak zgłaszać błędy.
6. Informacje prawne : licencja, prawa autorskie i wszelkie inne szczegóły prawne.

Napisanie „skoku sprzedaży” z góry zmusza mnie do krystalicznego wyjaśnienia, dlaczego ten projekt powinien istnieć i dlaczego deweloperzy powinni z niego korzystać. Sam akt pisania pełnych zdań opisujących projekt często zmienia go na lepszy: lepiej go rozumiesz, rozwijasz nowe pomysły i odkrywasz potencjalne problemy. To także świetne narzędzie do ustalania priorytetów: wszystko, co znajduje się w „dziale sprzedaży”, jest koniecznością!

„Szybkie przykłady” i „przewodnik szybkiego startu” zmuszają mnie do przemyślenia kluczowych przypadków użycia z perspektywy użytkownika. Przekonałem się, że zrobienie tego przed napisaniem jakiegokolwiek kodu - zanim zagłębię się w szczegóły implementacji i napięte terminy - prowadzi do znacznie czystszych interfejsów API i projektów. Pamiętaj: programy powinny być pisane dla ludzi do czytania, a tylko przypadkowo dla maszyn do wykonania ( SICP ).

W „dalszej dokumentacji” tworzę zarys elementów, które będą wymagały szczegółowej dokumentacji, która zostanie wykonana później. „Organizacja projektu” pozwala mi dowiedzieć się, kto będzie pracował nad projektem i praktykami kodowania. „Informacje prawne”… cóż, równie dobrze mogą je usunąć.

Po przygotowaniu tego podstawowego pliku README masz dokument przydatny do dyskusji, recenzji projektów, podziału pracy i planowania projektu. Podczas pracy nad projektem często sprawdzaj ponownie za pomocą README, aby upewnić się, że nadal jesteś na dobrej drodze. Ponadto stopniowa aktualizacja pliku README i „dalszej dokumentacji” w trakcie pracy oznacza, że cała twoja dokumentacja zostanie wykonana, gdy kod zostanie wykonany, co jest znacznie przyjemniejsze niż konieczność pośpiesznego dokumentowania wszystkiego w ostatniej chwili.

Aby uzyskać więcej informacji, sprawdź następujące elementy:

1. Rozwój oparty na plikach Readme
2. Najważniejszym kodem nie jest kod
3. Jesteś tym, co dokumentujesz

Dlaczego nie chcesz myśleć o interakcji klas? Dlaczego to zła rzecz? Właściwie myślę o interakcjach, zanim jeszcze wiem, jakie są klasy. W ten sposób klasy się identyfikują.

Powinieneś mieć pojęcie o tym, co planujesz zrobić przed napisaniem kodu. Problem zawsze polega na tym, jak zachować synchronizację tego, co napisałeś? Niektórzy mówią, że nie próbuj, inni zapominają o wstępnych dokumentach i kontynuują komentarze. Oczywiście kod jest zawsze źródłem kanonicznym. Wówczas pojawia się kwestia, czy warto udokumentować, co robi kod dla tych, którzy przyjdą później lub czy będą go używać. Każdy może dowiedzieć się, co robi funkcja. Zadaniem pisarza jest pomóc komuś zrozumieć w 5 minut, co każdy może dowiedzieć się w ciągu godziny. Dodaj delty i określ swoją ścieżkę.