http://blog.zabiello.com/articles/2006/03/06/dokumentacja-dla-leniwych-pot%C4%99ga-pythona en-us 40 moje notatki, linki, komentarze <p>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 &#8220;na później&#8221; 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ę)</p> <p>Aby ten problem rozwiązać, praktycznie wszyscy developerzy różnych języków zaczęli wymyślać różne metody aby ten proces usprawnić.</p> <p>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.</p> <p>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 <a href="http://java.sun.com/j2se/javadoc/">javadoc</a>, <a href="http://www.phpdoc.org/">phpdoc</a> czy <a href="http://stdlib.rubyonrails.org/">rubydoc</a>. 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.</p> <h2>Doctringi</h2> <p>Jednym z założeń leżących u podstaw Pythona jest przyjęcie zasady, że <a href="http://www.python.org/doc/Humor.html#zen">proste jest lepsze niż złożone</a>. 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 <a href="http://www.python.org/peps/pep-0257.html">docstringiem</a>.</p> <p>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:</p> <p><img src="http://blog.zabiello.com/images/articles/dla-leniwych1.png" alt="" /></p> <p>Każdy docstring mogę także wyświetlić tak:</p> <p><img src="http://blog.zabiello.com/images/articles/dla-leniwych5.gif" alt="" /></p> <p>W Pythonie (od wersji 2.4 wzwyż) można dodawać docstringi także do</p> <p><a href="http://www.cafepy.com/article/python_attributes_and_methods/python_attributes_and_methods.html">atrybutów</a>.</p> <p><img src="http://blog.zabiello.com/images/articles/dla-leniwych2.png" alt="" /></p> <p>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ą.</p> <h2>Pydoc</h2> <p>Standardowo każda dystrybucja Pythona wyposażona jest w prosty skrypt: pydoc (plik pydoc.py leży w folderze <em>lib</em> 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).</p> <p>Aby np. wyświetlić krótki manual na temat modułu md5 wystarczy że z poziomu shella wpiszemy np. <strong>pydoc modules md5</strong></p> <p><img src="http://blog.zabiello.com/images/articles/dla-leniwych3.png" alt="" /></p> <p>(Zamiast uruchamiać pydoc&#8217;a w shellu, można z poziomu interpretera wpisać: help(&#8216;md5&#8217;). uzyskamy ten sam efekt co pydoc odpalony z shella. Odpowiada to mniej więcej uniksowym manualom.)</p> <p>Można także wygenerować pliki html w stylu phpdoc&#8217;a albo po prostu odpalić na dowolnym porcie serwer www z dokumentacją do wszystkich modułów: <strong>pydoc -P 8080</strong></p> <p>Pod adresem http://localhost:8080 mamy witrynę z opisem wszystkich modułów Pythona zainstalowanych w systemie.</p> <p><img src="http://blog.zabiello.com/images/articles/dla-leniwych4.png" alt="" /></p> <p>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 &#8211; docstringach &#8211; mechanizmowi tworzenia dokumentacji do kodu dla leniwych. :) To jedna z wielu doskonałych cech Pythona.</p> Mon, 06 Mar 2006 16:18:00 +0100 urn:uuid:1481d214-4e8d-49e9-be88-7a260dfe743d Jarosław Zabiełło http://blog.zabiello.com/articles/2006/03/06/dokumentacja-dla-leniwych-pot%C4%99ga-pythona Python python