Dokumentacja dla leniwych - potęga Pythona

Opublikowane przez Jarosław Zabiełło Mon, 06 Mar 2006 15:18:00 GMT

Jedną z najbardziej nielubianych rzeczy przez programistów jest tworzenie dokumentacji do kodu. Wszyscy wiemy, że dobrze ją tworzyć, ale mało komu chce się na to poświęcać cenny czas zwłaszcza jak terminy ukończenia projektu gonią. W takich sytuacjach często dokumentację zostawia się zwykle “na później” jako zadanie do wykonania po ukończeniu projektu. Jednak czym innym jest dodanie komentarza do kodu na bierząco a czym innym napisanie go po paru tygodniach (zwłaszcza jak kod był tworzony zespołowo i musimy teraz zastanowić się co kolega Jasio miał na myśli tworząca jakąś tam kolejną funkcję)

Aby ten problem rozwiązać, praktycznie wszyscy developerzy różnych języków zaczęli wymyślać różne metody aby ten proces usprawnić.

Po pierwsze, stworzono parsery kodu źródłowego, który potrafią wyłuskać z wszystkich plików projektu definicje klas, metod, modułów. Taka pomoc, choć lepsza nic nic, generalnie niewiele jest warta, bo sprowadza się do wyświetlenia nazw klas i ich metod (No może dodatkowo z typami danych, jeśli językiem tym jest któryś z języków statycznie typowanych) Nie mówi jednak nic na temat funkcjonalności ani tego jak używać wyłuskany kod.

Aby temu zaradzić wymyślono inne podejście. Założono że programista przed każdą funkcją czy klasą będzie dodawał wielowierszowy komentarz wg ściśle określonej składni. I potworzono różnego rodzaju biblioteki javadoc, phpdoc czy rubydoc. Niby lepiej. Można teraz lepiej opisywać kod, ale nadal trzeba trzymać się specyficznej składni i znaczników. Poza tym, tak tworzona dokumentacja nie jest w żaden sposób związana z tworzonym kodem.

Doctringi

Jednym z założeń leżących u podstaw Pythona jest przyjęcie zasady, że proste jest lepsze niż złożone. Twórca Pythona, wychodząc naprzeciw zapotrzebowaniom programistów wpadł na genialnie prosty i wygodny zarazem sposób. Przyjął prostą zasadę: każdy fragment tekstu zaczynający się zaraz pod deklaracji klasy czy metody będzie automatycznie dołączany do tej klasy, metody jako jego osobista dokumentacja. Nazwano to docstringiem.

Jak wiemy, dobry programista do programista leniwy. Czyli taki, który stara się osiągać cel jak najmniejszym nakładem pracy. Docstring nie narzuca na programistę żadnych wymagań co do konieczności używania jakichś specjalnch znaczników. Po prostu, deklaruję funkcję. Zaraz pod nią wpisuję linijkę opisującą z grubsza do czego służy, i nie przerywając pracy, piszę dalej. W związku jednak z tym, że ten docstring staje się automatycznie częścią danej metody, mam natychmiastowy do niego dostęp z poziomu interpretera, ba, z poziomu konsoli:

Każdy docstring mogę także wyświetlić tak:

W Pythonie (od wersji 2.4 wzwyż) można dodawać docstringi także do

atrybutów.

Docstringi są bardzo wygodnym sposobem dodawania dokumentacji do kodu. Wymagają minimum wysiłku i wiedzy. To powoduje, że większość aplikacji Pythona tam, gdzie się ludzie śpieszą, powstaje własnie tą metodą.

Pydoc

Standardowo każda dystrybucja Pythona wyposażona jest w prosty skrypt: pydoc (plik pydoc.py leży w folderze lib razem z resztą modułów stadardowej biblioteki pythona. Pydoc umożliwia automatyczną generację dokumentacje do wszystkich modułów Pythona (zarówno tych z bibioteki standardowej jak i wszystkich jakie zainstalujemy).

Aby np. wyświetlić krótki manual na temat modułu md5 wystarczy że z poziomu shella wpiszemy np. pydoc modules md5

(Zamiast uruchamiać pydoc’a w shellu, można z poziomu interpretera wpisać: help(‘md5’). uzyskamy ten sam efekt co pydoc odpalony z shella. Odpowiada to mniej więcej uniksowym manualom.)

Można także wygenerować pliki html w stylu phpdoc’a albo po prostu odpalić na dowolnym porcie serwer www z dokumentacją do wszystkich modułów: pydoc -P 8080

Pod adresem http://localhost:8080 mamy witrynę z opisem wszystkich modułów Pythona zainstalowanych w systemie.

Istnieje znacznie więcej możliwości podpowiadania składni, uzupełniania kodu i innych udogodnień w Pythonie. Tu ograniczyłem się tylko do fragmentu, który nie ma odpowiednika w innych językach – docstringach – mechanizmowi tworzenia dokumentacji do kodu dla leniwych. :) To jedna z wielu doskonałych cech Pythona.

Posted in  | Tagi  | 1 comment

Comments

  1. Avatar miłośnik_django powiedział over 3 years later:

    Dzięki za artykuł! Nawet nie wiedziałem o istnieniu pydoc’a – a po jego uruchomieniu stwierdzam jednoznacznie, że jest to rewelacja. W firmie mamy ogromny system pythonowy, bez żadnej dokumentacji, pydoc będzie jak znalazł.

(leave url/email »)

   Pomoc języka formatowania Obejrzyj komentarz