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ć
documentation
łokieć
źródło
źródło
Odpowiedzi:
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.
źródło
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.
źródło
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.
źródło
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.
źródło
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.
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.
źródło
Niektórzy ludzie nawet idą dalej i twierdzą, że firma powinna całkowicie działać wstecz, więc
Zobacz http://www.allthingsdistribut.com.com/11/working_backwards.html
źródło
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:
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:
źródło
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ą.
źródło
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ę.
źródło