Engineering Insights
Ważną umiejętnością dla każdego inżyniera oprogramowania jest pisanie technicznych dokumentów projektowych (TDD), zwanych również inżynierskimi dokumentami projektowymi (EDD). W tym artykule oferuję kilka porad dotyczących pisania dobrych dokumentów projektowych i błędów, których należy unikać.
Jedno zastrzeżenie: Różne zespoły będą miały różne standardy i konwencje dla projektów technicznych. Nie istnieje żaden ogólnobranżowy standard dla procesu projektowania, ani nie może istnieć, ponieważ różne zespoły programistów będą miały różne potrzeby w zależności od sytuacji. To, co opiszę, jest jedną z możliwych odpowiedzi, opartą na moim własnym doświadczeniu.
Zacznijmy od podstaw: Czym jest techniczny dokument projektowy i jak wpisuje się on w proces projektowania?
Techniczny dokument projektowy opisuje rozwiązanie danego problemu technicznego. Jest to specyfikacja lub „plan projektu” dla programu lub funkcji.
Podstawową funkcją TDD jest przekazywanie członkom zespołu technicznych szczegółów pracy, która ma być wykonana. Istnieje jednak drugi cel, który jest równie ważny: proces pisania TDD zmusza do uporządkowania myśli i rozważenia każdego aspektu projektu, zapewniając, że nic nie zostało pominięte.
Techniczne dokumenty projektowe są często częścią większego procesu, który zazwyczaj składa się z następujących kroków:
- Definiowane są wymagania dotyczące produktu. Zazwyczaj będą one reprezentowane przez Dokument Wymagań Produktowych (PRD). Dokument PRD określa, co system musi robić z perspektywy użytkownika lub agenta zewnętrznego.
- Definiowane są wymagania techniczne. Wymagania produktowe są tłumaczone na wymagania techniczne – co system musi osiągnąć, ale teraz jak to zrobi. Wynikiem tego kroku jest Dokument Wymagań Technicznych (TRD).
- Projekt techniczny. Zawiera on techniczny opis rozwiązania dla wymagań przedstawionych w poprzednich krokach. TDD jest wyjściem tego kroku.
- Implementacja. Jest to etap, w którym rozwiązanie jest faktycznie budowane.
- Testowanie. System jest testowany względem PRD i TRD, aby zapewnić, że rzeczywiście spełnia określone wymagania.
Pomiędzy każdym z tych etapów zazwyczaj odbywa się proces przeglądu, aby upewnić się, że nie popełniono żadnych błędów. Jeśli zostaną wykryte jakiekolwiek błędy, nieporozumienia lub niejasności, muszą one zostać skorygowane przed przejściem do następnego etapu.
Proces ten jest bardzo zmienny; zestaw wymienionych tu kroków będzie się zmieniał w zależności od przypadku. Na przykład:
- Dla mniejszych funkcji, które nie wiążą się z dużą złożonością, kroki 2 i 3 będą często łączone w jeden dokument.
- Jeśli funkcja wiąże się z dużą liczbą niewiadomych lub pewnym poziomem badań, może być konieczne skonstruowanie implementacji proof-of-concept przed sfinalizowaniem projektu technicznego.
Ten proces również zachodzi w różnej skali i na różnych poziomach ziarnistości. PRD / TRD / TDD może dotyczyć projektu całego systemu, lub tylko pojedynczej funkcji. W większości środowisk, proces ten jest również cykliczny – każdy cykl projektowania/implementacji opiera się na pracy poprzedniego.
Linia podziału pomiędzy TRD i TDD może być czasami nieco rozmyta. Na przykład, załóżmy, że tworzysz serwer, który komunikuje się poprzez RESTful API. Jeśli celem jest dostosowanie się do już ustanowionego i udokumentowanego API, wtedy specyfikacja API jest częścią wymagań i powinna być przywoływana w TRD. Jeśli, z drugiej strony, celem jest stworzenie zupełnie nowego API, wtedy specyfikacja API jest częścią projektu i powinna być opisana w TDD. (Jednakże, dokument wymagań nadal musi określać, co API próbuje osiągnąć.)
Pisanie TDD
W dzisiejszych czasach, powszechną praktyką jest pisanie dokumentów technicznych w systemie dokumentów współpracujących, takich jak Google Docs lub Confluence; jednakże nie jest to bezwzględny wymóg. Ważne jest, aby członkowie zespołu mieli możliwość komentowania dokumentu i wskazywania błędów i przeoczeń.
Większość TDD ma od jednej do dziesięciu stron. Chociaż nie ma górnej granicy długości TDD, bardzo duże dokumenty będą zarówno trudne do edycji, jak i trudne do przyswojenia dla czytelników; rozważ rozbicie go na oddzielne dokumenty reprezentujące poszczególne kroki lub fazy wdrożenia.
Diagramy są pomocne; istnieje wiele narzędzi online, które można wykorzystać do osadzenia ilustracji w dokumencie, takich jak draw.io lub Lucidchart. Możesz również użyć narzędzi offline, takich jak Inkscape, aby wygenerować diagramy SVG.
Dokument powinien być dokładny; idealnie, powinno być możliwe dla kogoś innego niż autor TDD, aby zaimplementować projekt tak, jak napisano. Na przykład, jeśli projekt określa implementację API, każdy punkt końcowy API powinien być udokumentowany. Jeśli istnieją subtelne wybory projektowe, powinny być wskazane.
Unikaj typowych błędów w pisaniu
Prawdopodobnie najczęstszym błędem, jaki spotykam w TDD jest brak kontekstu. Oznacza to, że autor napisał, w tak niewielu słowach, jak tylko mógł, jak rozwiązał problem, ale nie zawarł żadnych informacji na temat tego, co to był za problem, dlaczego trzeba było go rozwiązać lub jakie były konsekwencje wybrania tego konkretnego rozwiązania.
Ważne jest również, aby pamiętać, kto jest prawdopodobnym czytelnikiem i jaki poziom zrozumienia posiada. Jeśli używasz terminu, którego czytelnik może nie znać, nie bój się dodać jego definicji.
Nie trzeba chyba stwierdzać, że dobra gramatyka i ortografia są pomocne. Unikaj również pokusy gry słów lub „słodkiej” pisowni; podczas gdy programiści jako klasa mają tendencję do lubienia zabawy językiem, widziałem więcej niż jeden przypadek, w którym nadmierna frywolność skończyła się kosztem zmarnowanego wysiłku zespołu z powodu nieporozumień. W porządku jest używanie okazjonalnego humoru lub wybieranie kolorowych, zapadających w pamięć nazw dla funkcji i systemów, ponieważ pomaga to ludziom je zapamiętać. Ale nie pozwól, aby twoje pragnienie popisania się tym, jaki jesteś sprytny, stało się rozpraszające.
Mówiąc o nazwach, wybieraj je ostrożnie; jak napisał kiedyś Mark Twain: „Wybierz właściwe słowo, a nie jego drugiego kuzyna”. Istnieje tendencja dla inżynierów z ubogim słownictwem do używania tych samych ogólnych terminów w kółko dla różnych rzeczy, co prowadzi do przeciążenia i zamieszania. Na przykład, nazwanie klasy „DataManager” jest niejasne i nie mówi nic o tym, co ona właściwie robi; z tego samego powodu pakiet lub katalog o nazwie „utils” może zawierać praktycznie wszystko. Skonsultuj się z tezaurusem, jeśli potrzebujesz znaleźć lepsze słowo, lub lepiej, wyspecjalizowaną bazę synonimów, taką jak WordNet.
Szablon TDD
Przy pisaniu TDD, pomocne może być rozpoczęcie od standardowego szablonu. Poniżej znajduje się szablon, którego używałem w wielu projektach. Zauważ, że ten szablon powinien być dostosowany tam, gdzie jest potrzebny; możesz swobodnie usuwać sekcje, które nie mają zastosowania, dodawać dodatkowe sekcje lub zmieniać nazwy nagłówków, jeśli jest to właściwe.