Dokumentowanie projektu – cz. I
Tworząc aplikację internetową wcześniej czy później spotkamy się z problemem jak szybko i wygodnie stworzyć dokumentację projektu? Jaki schemat zastosować, by był czytelny dla zespołu programistów (również dla tych nowych w grupie)? Z pomocą przychodzi nam PHPDoc, który staje się (a właściwie już jest) standardem komentowania i tworzenia dokumentacji w świecie PHP. W pierwszej części artykułu przedstawię sposoby poprawnego komentowania kodu. Natomiast w drugiej zaprezentuję jak szybko wygenerować dokumentację projektu.
Schemat komentarza
Aby poprawnie wygenerować dokumentację w PHPDoc komentarz musi mieć następujący schemat:
/** * @atrybut * * komentarz ... */
Uwaga: istotne są również białe znaki (spacje, entery itp).
Komentowanie pliku
Na początku każdego pliku warto zamieścić informacje na temat autora, wersji pliku czy licencji.
/** * @author Łukasz Socha <kontakt@lukasz-socha.pl> * @copyright Łukasz Socha * @version: 1.0 * @license http://www.gnu.org/copyleft/lesser.html * * Opis pliku ... */
Opis atrybutów:
- @author – informacja na temat autora
- @copyright – notka na temat praw autorskich
- @version – wersja skryptu
Komentowanie klasy
Komentarz dotyczący klasy zawsze stawiamy przed definicją klasy:
/** * @package pakiet (np: core) * @subpackage subpaket (np: loader) * @abstract * @todo co do zrobienia ... * @final * @deprecated * @example /sciezko/do/przykladu */
Opis atrybutów:
- @package – pakiet, do którego należy dany fragment kodu
- @subpackage – subpakiet
- @abstract – oznaczenie klasy abstrakcyjnej
- @todo – informacja co należy jeszcze zrobić
- @final – oznaczenie klasy finalnej
- @deprecated – oznaczenie przestarzałego fragmentu
- @example – ścieżka do pliku z przykładem
Komentowanie pól i metod
/**
* @var int
* @static
*
* Opis pola
*/
private static $liczba;
/**
* @since od
* @static
* @param string $param1 parametr metody
* @return void
*
* Opis metody
*/
public function metoda($param1) {
}
Opis atrybutów:
- @var – typ pola
- @static – oznaczenie pola/metody statycznej
- @since – informacja odkąd dany fragment istnieje
- @param – opis parametru (typ $nazwa opis)
- @return – typ zwracany przez metodę (typ)
Zakończenie
Oczywiście nie jest to pełen zbiór atrybutów (pełen opis znajduje się na stronie projektu). Jednak starałem się opisać te najczęściej używane. W kolejnej części zaprezentuję jak wygenerować dokumentację wykorzystując powyższy wzorzec komentowania.
Powiązane tematy
