dokumentacja kodu

Pracowałem kiedyś przy projekcie, w którym robiłem pewien moduł w znacznym stopniu niezależny od reszty systemu (sam go zaprojektowałem i sam zaprogramowałem), mogłem więc obserwować całość z boku. W sumie działało tam ośmiu programistów, o różnym stażu, różnych doświadczeniach i umiejętnościach, nawet rozmieszczonych w niemal krańcowo odległych lokalizacjach w Polsce. Oprócz mnie może jeszcze jedna osoba tworzyła w kodzie komentarze dla zwiększenia jakości kodu, a nie dla wyrażenia swoich frustracji[1]. Oprócz mojego żaden moduł programu nie posiadał kompletu własnej dokumentacji. A całość była pisana w javie, więc stworzenie sensownej i kompleksowej dokumentacji kodu (z użyciem Javadoc) wymagało jedynie odrobiny dobrej woli...

To oczywiście nie jest żaden przypadek szczególny — nawet zaryzykuję stwierdzenie, że to reguła. Komentowanie kodu zazwyczaj jest traktowane po macoszemu (że niby nie ma czasu, nie ma ochoty, a nawet niektórzy twierdzą, że nie ma potrzeby), choć równocześnie wszyscy mają świadomość, że za pół roku nikt sobie nie przypomni o co w danym kodzie właściwie chodzi, a jeśli projekt przejmie inny zespół produkcyjny to już w ogóle znajdą się w bagnie po uszy. Oczywiście "self documenting code"[2] jest do pewnego stopnia rozwiązaniem (bardzo ładnie opisuje co się dzieje w danej linii czy pętli), ale nie udzieli odpowiedzi na pytanie "po co to jest? dlaczego akurat tak? do czego w ogóle cały ten kod służy? jak to wygląda w kontekście całego systemu i z której strony to ugryźć?". Dokumentacja opisowa jest IMHO konieczna jeśli w tworzeniu kodu uczestniczy więcej niż 3 osoby a projekt ma reprezentować sobą cokolwiek wartego uwagi. Najlepiej aby była generowana jakoś automagicznie i nie wymagała przechowywania i wersjonowania oddzielnie od kodu, którego dotyczy (inaczej nie uniknie smutnego losu dokumentacji użytkownika, która jest skazana na brak aktualności).

Prawdopodobnie nie jestem w tej opinii osamotniony, co można wywnioskować na podstawie ilości narzędzi do tworzenia dokumentacji kodu. Przyjrzyjmy się pobieżnie kilku, które akurat mam pod ręką:

Javadoc

Javadoc było chyba pierwszym narzędziem tego typu z jakim się zetknąłem na poważnie. Zapewne jego wszystkich możliwości nie zgłębiłem do końca, ale to, co udało mi się poznać, było wystarczająco imponujące, aby uznać funkcjonowanie tego typu narzędzia za konieczne w każdym w miarę profesjonalnie prowadzonym projekcie.

Zasada działania Javadoc opiera się na analizie specjalnie spreparowanych komentarzy w kodzie i wygenerowaniu na ich podstawie zestawu plików HTML (w postaci np. takiej jak specyfikacja API javy). Na krótkim przykładzie może to wyglądać tak:

/**
 * Klasa główna engine'u bloga. Zapewnia całościową obsługę 
 * użytkowników aplikacji oraz zarządzanie wpisami, w tym: 
 * <ul>
 * <li>dodawanie i edycję nowych wpisów</li>
 * <li>publikację jako HTML i XML</li>
 * <li>zarządzanie archiwum</li>
 * <li>przeszukiwanie treści</li>
 * </ul>
 *
 * @author  MiMaS
 * @author  Trevor the Toad
 * @version 1.7
 * @see  <a href="{@docRoot}/blog.html">dokumentacja</a>
 * @see  Post
 * @see  User
 * @see  SearchFactory
 */
class Blog {

 /**
  * Publikacja. W razie konieczności generowane 
  * są nowe strony wynikowe i opcjonalnie również 
  * {@link Blog#syndicate pliki XML}. Szczegóły generacji 
  * zależne od {@link Blog#configure konfiguracji}.
  * 
  * @return <code>true</code> jeśli wygenerowano nowe pliki;
  *         <code>false</code> brak konieczności gneracji
  * @throws SecurityException jeżeli brak użytkownika
  * @see Blog#configure
  * @see Blog#preview
  * @see <a href="{@docRoot}/pub.html">dokumentacja</a>
  * @since 1.0
  */
 public boolean publish() throws SecurityException { ...

Na podstawie konwencji Javadoc powstało kilka podobnych narzędzi dla innych języków, np. PHPdoc, a wykorzystywany tutaj format zapisu komentarzy jest na tyle popularny, że wykorzystują go też inne narzędzia, np. Doxygen (patrz niżej).

XML Documentation w C#

Generator dokumentacji dla języka C# zawarty w Visual Studio .NET wprowadza do całej zabawy wszędobylski XML ze specjalnym zestawem tagów.

/// <summary>
/// Podgląd wpisu. Nie tworzy faktycznego wpisu, 
/// nie następuje publikacja.
/// <seealso cref="Blog.Preview"/>
/// <seealso cref="EditForm.IB_Publish_Click"/>
/// </summary>
/// <exception cref="System.Security.SecurityException">
/// brak zalogowanego użytkownika</exception>
private void IB_Preview_Click(object sender, 
  System.Web.UI.ImageClickEventArgs e) { ...

Generalna zasada jest oczywiście identyczna jak w przypadku Javadoc, choć mam wrażenie, że świat .NET jest na tym polu lekko z tyłu. Niestety generator dokumentacji HTML wbudowany w dostępnej mi wersji Microsoft Development Environment 2003 (aka Visual C#.NET) skutecznie ignoruje w powyższym przykładzie zarówno tag <seealso> jak i <exception> :-/ Przynajmniej w wygenerowanej dokumentacji XML niczego nie brakuje.

Doxygen

Doxygen jest generatorem dokumentacji dla różnych języków wykorzystywanym w wielu różnych projektach (w tym również w KDevelop, dzięki czemu wpada w zakres moich zainteresowań). Narzędzie to posiada potencjalnie ogromne możliwości, łącznie z generowaniem grafiki przedstawiającej diagramy klas. Styl komentarzy dokumentacyjnych może być stosunkowo dowolny (jak w Javadoc albo w stylu Qt) a dodatkowo (po)mieszany (jak w przykładzie poniżej). Co prawda stosowanie różnych koncepcji komentowania w ramach jednego projektu jest generalnie błędem (organizacyjnym), ale dobrze mieć wybór ;-)

/**
 * @brief Wpis bloga
 * 
 * Klasa reprezentująca jeden wpis bloga.
 * @version 2.0
 * @author MiMaS
 */
class Post {
public:
  /// Konstruktor pustego wpisu. Timestamp ustawiany 
  /// na aktualny, autor na zalogowanego użytkownika, 
  /// tytuł i treść puste, kategoria domyślna 
  /// wg konfiguracji.
  /// @see Post(QDateTime, PostAuthor, QString, 
  ///           PostCategoryList, PostText)
  /// @see Blog::Configure()
  Post();
    
  /*!
   Konstruktor wpisu z wyszczególnieniem atrybutów.
   \param timestamp timestamp publikacji
   \param author autor wpisu
   \param title tytuł, może być null
   \param categories lista kategorii wpisu, może być null
   \param text treść wpisu, nie może być pusta
   \sa Post()
   \warning konstruktor pozostawiony dla kompatybilności 
            z 1.0, używaj raczej \ref Post()
   */
    Post(QDateTime timestamp, 
         PostAuthor author, 
         QString title, 
         PostCategoryList caterogies, 
         PostText text);
...

Format powstałej w wyniku działania takich narzędzi dokumentacji nie jest może najistotniejszy, choć oczywicie najprzyjemniej by było gdyby był to HTML (i tak jest najczęściej) lub XML, PDF, czy inny szanowany format. Jednak już sam fakt istnienia takiej dokumentacji jest znaczną wartością w projekcie — nie sposób tego nie docenić, zwłaszcza jeśli jest się nowym członkiem zespołu, albo przejmuje się projekt po poprzedniej ekipie.

Włóżcie w to odrobinę pracy — wcale tak bardzo nie boli...

[1] Komentarze niemerytoryczne, wyrażające najczciej negatywny stosunek do jakiegoś kawałka kodu, do jakiejś niewygodnej konstrukcji lub generalnie do własnej pracy są w dużych projektach zaskakująco częste. Nawet w tak "zawodowej" firmie jak Microsoft, o czym można się było przekonać niedawno na podstawie fragmentów kodu Windows 2000. Podobnie z komentarzami zawierającymi alternatywną (lub poprzednią(!), jakby nie istniały systemy kontroli wersji) postać jakiegoś specyficznego, zazwyczaj "trudnego" kodu. Takich popisów grafomaństwa nie traktuję w tym momencie w ogóle jako komentarzy.

[2] "Self documenting code", czyli kod stanowiący dokumentację samą w sobie, nie jest jakąś szczególną egzotyczną techniką, a raczej wymogiem i naturalnym odruchem każdego(?) programisty — kod napisany tak, żeby każdy widział o co w nim chodzi[3], a przede wszystkim, żeby sam autor umiał się w tym kodzie zorientować za pół roku. Polega to głównie na nadawaniu sensownych nazw zmiennych, klas i metod, stosowaniu stałych zamiast "gołych" liczb itp. oraz na trzymaniu się jakiejś spójnej koncepcji w całym kodzie (przynajmniej w obrębie jakiegoś merytorycznie spójnego fragmentu). Śmiem twierdzić, że brak odruchu tworzenia takiego kodu cechuje kogoś, kto dla dobra świata programistą być nie powinien.

[3] Celowe zaciemnienie kodu z powodów np. politycznych to zupełnie inna bajka i nie wchodzi w zakres rozważań o sztuce programowania. Choć w krajobraz grzęzawiska jak najbardziej.

2004.04.14 | skomentujesz? | RDF

tagi » ,

Komentarze

Brak komentarzy do tego wpisu.

 

Uwaga: Ze względu na bardzo intensywną działalność spambotów komentowanie zostało wyłączone po 60 dniach od opublikowania wpisu. Jeżeli faktycznie chcesz jeszcze skomentować skorzystaj ze strony kontaktowej.