Projektowanie dobrego API nigdy nie było łatwe, o czym świadczy chociażby implementacja IOleCommandTarget::Exec, czy też niedawno wypuszczony SharePoint 2007. Co z tego, że nasz produkt pozwala nam zbudować roller coster (rysunek 8), kiedy dla innych udostępniamy jedynie huśtawkę zamiast pnia (rysunek 3) – link, zapożyczyłem rysunek z procesu tworzenia oprogramowania, ale mniej więcej tak wygląda API, które w większości jest udostępnione programistom.
Problem tworzenia dobrego API istnieje od zawsze i z będzie istniał zawsze, jedynie co my możemy zrobić to ułatwić sobie proces tworzenia API tak by móc się nawzajem informować co należałoby poprawić i dlaczego. Aktualnie mamy diagram klas, opis diagramu, .NET Reflector oraz Object Browser w VS i samo VS. To nam umożliwi przejrzenie API i jak będziemy mieli jakieś uwagi, to zapiszemy to w osobnym dokumencie i prześlemy do wszystkich zainteresowanych.
No tak, ale kiedy mamy 100 klas, z czego ponad połowa udostępniona jest jako API zewnętrzne i teraz mielibyśmy przeglądać diagram tych klas, i na podstawie diagramu tworzyć opisy to można by dostać kociokwiku od samej ilości klas a co dopiero kiedy taka jedna klasa ma 20 metod i 15 własności? I w której przestrzeni nazw się ona znajduje? Jakby do tego jeszcze użyć Object Browser to już w ogóle może szlak człowieka trafić. No dobrze, mamy .NET Reflectora, który umożliwi nam dość łatwe przejrzenie kodu, ale co z komentarzami? Możemy wykorzystać już dostępny plug-in, jednak .NET Reflector udostępnia znacznie za dużo, to znaczy zamiast koncentrować się czysto na API możemy zbędnie zagłębiać się w implementacje, ja to widzę tak, jakbyśmy chcieli zapisać numer telefonu do znajomego za pomocą napisania aplikacji, która za pomocą e-mail prześle nam telefon na naszą skrzynkę pocztową. Do prostego i ograniczonego zadania zaciągamy parowóz.
Jeszcze innym rozwiązaniem jest wykorzystanie VS do przeglądania kodu i udostępnionego API, jednak znów – parowóz, poza tym, IMO w .NET Reflector łatwiej jest się poruszać po typach i metodach niż w VS, nawet z wykorzystaniem R#.
Mamy jeszcze jedną opcję, wykorzystać Framework Design Studio stworzone przez Krzysztofa Cwaline, Hongping Lim, Davida Fowlera oraz Nicka Moloneya. Studio to, umożliwa cztery podstawowe funkcje:
- Przeglądanie API;
- Komentowanie API;
- Porównywanie dwóch wersji API;
- Eksport do MS Word.
Przeglądanie API jest podobne do tego co mamy w .NET Reflector, z tą różnicą, iż nie zagłębiamy się w implementacje poszczególnych metod.
Porównywanie dwóch wersji API umożliwia podgląd tego co zostało usunięte z jednego API, to co zostało nie zmienione oraz to co zostało dodane – na czerwono to co zostało usunięte, na zielono to co zostało dodane, na czarno bez zmian zaś na szaro to co zostało odziedziczone.
Komentowanie, jest tak samo proste jak w Word, zaznaczamy fragment kodu, który chcemy z komentować, klikamy prawym przyciskiem myszy i zaznaczamy Add Comment.
Zaś eksport do Word… fajnie że jest, ale osobiście jak widzę kod źródłowym w dokumencie i to jeszcze ułożonym poziomo (landscape), to przypomina mi się książka na która swojego czasu natrafiłem w Anglii: Kod źródłowy kernela. Po prostu ręce mi opadły, ja wiem, że kiedyś tak się „analizowało” kod i czasami nawet dalej robi… ale wydawać książkę, która zaczyna się od linijki kodu, w środku jest kod i na końcu też jest kod to już przesada. Nie licząc, że zawijanie linii było dość fatalnie zorganizowane przez co czytało się to jeszcze gorzej :/ ale co zrobić kiedy się czeka na premierowe wydanie 2 tomu Harrego Pottera bez którego do domu lepiej nie wracać bo siostra oczy wydłubie ;) Jednak niektórzy mogą uznać to za fajny feature ;)
Nie twierdzę, że FDS załatwi wszystko, ale jest to przyjemne narządko, dzięki któremu możemy szybko i sprawnie przeprowadzić recenzje naszego API przy czym nie będziemy kuszeni zrobieniem czegoś więcej niż czystej recenzji.
Czy wam przypadnie do gustu jak i mi, to zależy :) jednak mam nadzieję, że chociaż na to rzucicie okiem i sami zadecydujecie czy jest to fajnie :) czy jest to kolejny beznadziejny produkt nikomu do szczęścia nie potrzebny :)
