Dokumentacja kodu Najpierw? [Zamknięte]

11

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ć

łokieć
źródło
2
Tak. To dobry pomysł. Ludzie robią to cały czas. Co jeszcze chcesz wiedzieć?
S.Lott,
9
To jest subiektywne pytanie. Ktoś to robił przynajmniej przez pewien czas, więc odpowiedź musi brzmieć „tak”. Ja osobiście wolę po prostu wskoczyć i zrobić prototyp jako pierwszy, ponieważ nieuchronnie odkryję lepszy projekt około 5 razy w tym procesie. Kiedy walczę z czymś złożonym, najpierw drapię coś na kartce papieru. Jeśli jest to trywialne, to po prostu wskakuję do środka. StyleCop pomaga mi później uzupełnić luki.
Job
2
To świetny pomysł, w przeciwnym razie uzyskasz nieudokumentowane funkcje.
Chris
8
@ S.Lott prosty fakt, że zadaje pytanie sugeruje, że szuka on dodatkowych informacji, ponieważ jestem pewien, że byłeś tego świadomy. Wygląda jednak na to, że wolisz komentować złośliwie komentarze o wadach innych ludzi.
Kenneth
2
Byłoby jeszcze lepiej, gdybyś napisał testy akceptacyjne, a następnie użył TDD do spełnienia tych testów akceptacyjnych;).
Martin Blore,

Odpowiedzi:

5

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.

Maks
źródło
12
Łatwiej to naprawić, tak. Rzadko łatwiej zauważyć. Projekty prawie zawsze wyglądają dobrze, dopóki nie spróbujesz ich zaimplementować.
CaffGeek
@Chad To prawda. Zredagowałem swoją odpowiedź, aby to odzwierciedlić.
Maks.
4
Nie zgadzam się. Najpierw tworzenie kompletnej dokumentacji jest znacznie gorsze niż wystarczająca dokumentacja, aby wiedzieć, gdzie iść dalej. Zmiana się dzieje. Nie ma sposobu, aby wiedzieć, czy idziesz w dobrym kierunku, a zanim to zrozumiesz, jesteś daleko w tyle. Idź z tym, co działa, poprawiaj i naprawiaj go w trakcie pracy, niech kod będzie najbardziej aktualną dokumentacją.
Zachary Scott
4
Oczywiście, jak tylko zmienisz kod, aby naprawić błąd lub spełnić nowy wymóg, twoja dokumentacja jest nieaktualna. Dokumentacja jako testy wykonywalne to najlepsza metoda!
Johnsyweb 18.03.11
Przygotuj wcześniej (szkic / konspekt) pomysły tak, ale nie twórz dokumentacji. Chyba że wolisz marnować dużo wysiłku, ponieważ będziesz wyrzucać dużo początkowego wysiłku, ponieważ projekt zostanie zastosowany w praktyce. Dodatkowo, tylko publiczne / wewnętrzne klasy / metody powinny być w pełni udokumentowane (w tym pełny opis oraz parametry). Prywatne rzeczy lokalne powinny mieć jedno linijki opisujące to, co robią na przyszłość, ale wszystko inne jest marnotrawstwem, ponieważ i tak nieuchronnie zostaną pominięte podczas fazy tworzenia dokumentacji.
Evan Plaice,
10

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.

Jurij Zubariew
źródło
2
+1 dla TDD. Absolutnie lepsza opcja niż dokumentowanie, a następnie zmiana znacznej ilości dokumentacji w przypadku zmiany kodu.
Ethel Evans,
Również +1 za dokumentację w formie TDD.
sevenseacat
MOŻESZ mieć pełną dokumentację produktu, zanim produkt będzie istniał. Zrobiłem to, pracowałem w projektach, w których było to wymagane. Nie będziesz mieć zrzutów ekranu, ale możesz mieć wszystko inne (w tym diagramy Visio przedstawiające położenie elementów na ekranie).
jwenting
@jwenting Też mam i był to zbiór diagramów, a także ponad 200 stron dokumentów tekstowych. Nie tylko była to strata czasu, ale wymagała 2 miesięcy na wyprodukowanie i znacznej ilości naszych PMs na ciągłą aktualizację wraz z ewolucją projektu w produkt końcowy. Prawdopodobnie poszedłby znacznie szybciej z makietami graficznymi używającymi Balsalmiq. Następnym razem, gdy będę pracować nad projektem, w którym jest to wymóg, zamierzam wskazać, że należy wyznaczyć inną osobę do zarządzania nim w pełnym wymiarze godzin, ponieważ tyle wysiłku wymaga utrzymanie.
Evan Plaice,
+1 TDD dla podstawowych prób pojedynczych elementów i schematów dla ogólnych założeń projektowych (nacisk na założenie, ponieważ rzeczywisty projekt powinien być napisany jako najlepsze praktyczne zastosowanie, a nie jako implementacja schematu 1-1, nazywane są założeniami z jakiegoś powodu ). Pełna dokumentacja oprogramowania wszystkich publicznych / wewnętrznych klas / metod / właściwości jest dostarczana na końcu przez generator dokumentacji (wszystkie właściwości / zwroty / uwagi powinny być wypełnione jako pierwsze), a wszystkie prywatne / lokalne rzeczy otrzymują jednowierszowe opisywanie tego, co robią na przyszłość. (prywatny / lokalny jest ignorowany przez generator).
Evan Plaice,
7

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
Dokładnie! Zmiana się dzieje. Dokumentacja gnije. Kod jest najprawdziwszą formą dokumentacji.
Zachary Scott
3

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.

Kenneth
źródło
3

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.

DPM
źródło
To dobra rada, ale dobra dokumentacja obejmuje użycie interfejsu API.
Frank Hileman
Dla przypomnienia, choć doceniam edycję, myślę, że ten cytat mógł nie być tym, o którym myślałem. Wydaje się, że jest to stycznie powiązane i bardziej wysokie lub związane z fazą wymagań. Myślę, że powiedział, że przed napisaniem dokumentacji zacznie kodować, pisząc kod klienta, który będzie korzystał z interfejsu, aby mieć ogólne pojęcie o odpowiednim interfejsie i że (według mnie jest to część sprzeczna z intuicją) powinien być na pierwszym miejscu, przed napisaniem jakiegokolwiek dokumentu projektowego niskiego poziomu. Oczywiście to moja wina, że ​​nie znalazłem cytatu, kiedy napisałem tę odpowiedź.
DPM
1

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

asmaier
źródło
1

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
Jewgienij Brikman
źródło
0

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ą.

Maczać
źródło
0

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ę.

SnoopDougieDoug
źródło