Jak napisać specyfikację implementacyjną?

Witam. Po długim czasie udało mi się zamieścić na blogu wpis mówiący o tym, jak napisać specyfikację IMPLEMENTACYJNĄ.

Należy jednak pamiętać, że artykuł ten mówi o AKADEMICKIEJ WERSJI SPECYFIKACJI IMPLEMENTACYJNEJ, czyli takiej, która jest wystarczająca do projektów własnych i nie ma nic wspólnego z wersją Enterprise.

Jest to drugi dokument, który zawiera wszystkie szczegółowe informacje dotyczące implementacji projektu począwszy od algorytmów, na nazwach zmiennych skończywszy. Oczywiście nadmienię, że jest to mój przepis na specyfikację implementacyjną, wyniesiony z zajęć na uczelni - aczkolwiek jak najbardziej spełnił swoje zadanie. Chodzi bowiem o to, by przemysleć i zaplanować wszystkie techniczne aspekty naszego projektu(funkcjonalność i metody implementacji) przed rozpoczęciem programowania. Nieocenioną wygodą okazał się w praktyce ten właśnie dokument, do którego wystarczyło tylko zaglądać w przypadku wątpliwości, jak dane zagadnienie powinno być rozwiązane, nie martwiąc się o to już przy kodowaniu. Ponadto dokument ten służy usystematyzowaniu projektu, by nie wymykał się spod "kontroli", by zbytnio się nie rozrastał, ani nie był za mały - dlatego dobrze napisana specyfikacja implementacyjna(jak i również funkcjonalna) jest równie ważna jak samo programowanie. Po tym przydługim wstępie czas na konkrety:

Rozdział 1: Informacje ogólne: Ja w tym rozdziale umieściłem ogólne parametry uruchomieniowe programu, np. wielkość okienka, styl domyślny, położenie okna po uruchomieniu.

Rozdział 2: Opis modułów/pakietów:>
Podrozdział: Moduł/pakiet - opis: W każdym z podrozdziałów opisujemy oddzielny moduł programu tzn. główne zadanie i powiązania między innymi modułami.

Rozdział 3: Opis klas:
Podrozdział: Klasa - opis: W tym rozdziale opisujemy w jakim pakiecie znajduje się klasa, po czym dziedziczy, jakie klasy implementuje, jakie spełnia zadanie biznesowe, krótko opisujemy konstruktor.

Podpodrozdział: Metoda: Opisujemy oraz metody, a także pola wraz z nazwami i zwięzłą definicją. Prototyp: nagłówek metody. Zadanie: cóż czyni. Algorytm: jak to czyni - krok po kroku. Wartość zwracana: co zwraca.

(opcja) Rozdział 4: Jak widać w opisie logiki programu przechodzimy od ogółu do szczegółu i jeśli programujemy np. w Javie, i jeśli implementujemy GUI, to opisujemy też (wtedy będzie to rozdział 4) słuchaczy akcji dla każdego z pól, przycisków, paneli itp. Jest to w tym przypadku i w tej specyfikacji bardzo ważne, ponieważ dobry opis pola i jego słuchacza akcji odciąży w momencie programowania nas z zastanawiania się "jak to powinno być zrobione?", by móc spokojnie zająć się tym, by to po prostu było zrobione (jednakże należy pamiętać, że licho nigdy nie śpi i powinniśmy przeznaczyć niewielką część uwagi na poprawność rozwiązania).

(opcja) Rozdział 5: Jeśli programujemy GUI, to tworzymy również rozdział numer 5, w którym opisujemy budowę wewnętrzną GUI - w moim wypadku był to obrazek z oknem programu i zaznaczonymi panelami, gdyż gdzieniegdzie stopień zagnieżdżenia panelu w panelu (i jeszcze w panelu i w panelu) był wysoki.

Rozdział 6: Testowanie.
Podrozdział 6.1: Użyte narzędzia.
Opisujemy, czy do testowania programu zatrudnimy Mamę, program podeślemy kumplowi, oddamy do firmy zajmującej się testowaniem, czy sami zaimplementujemy tyle testów, że zajmą 5x więcej kodu niż sama aplikacja. Przykładem takiego narzędzia do wspomagania testów jest JUnit.

Podrozdział 6.2: Konwencja.
Myślę, że może to być ciekawy punkt w specyfikacji dla wykonującego. Zwolnimy go/siebie z myślenia podczas implementacji. Chodzi bowiem o fajne i logiczne rozplanowanie wyglądu i sposobu pisania testów. Na przykład zamiast pisać metody "testLogin()", czemu nie napisać "shouldLogInUserForCorrectInput()" lub "shouldShowErrorMessageForIncorrectLoginInput()". Takie nazwy metod więcej mówią nam o przeprowadzanym teście. Łatwe i prawda, że fajne?

Podrozdział 6.3: Warunki brzegowe.
Warto wymienić jakie warunki brzegowe i miejsca potencjalnie błędne chcemy przetestować. To jest ważne.

Rozdział 7 to rzecz bardzo ważna: Diagram klas. W celu stworzenia diagramu klas trzeba znać oczywiście podstawy UML. Ponadto przydatne są programy przeznaczone do tego celu. Polecam EnterpriseArchitect'a, który w wersji 30-dniowej jest darmowy. Aplikacja ta pozwala w prosty sposób stworzyć samodzielnie diagram klas, bądź wygenerować go na podstawie isniejącego kodu lub wygenerować kod na podstawie diagramu. Gdy byłem w potrzebie szukałem innego darmowego narzędzia do tworzenia diagramu klas na podstawie kodu, lecz każde z znalezionych miało jakąś wadę lub braki (np AgroUML, StarUML, BOUML).

I to byłoby na tyle w temacie akademickiej specyfikacji implementacyjnej.
Pozdrawiam i miłego projektowania!