post_ico4

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

Co sądzisz o wpisie?
BeżnadziejnySłabyŚredniDobryBardzo dobry (Brak ocen, bądź pierwszy!)
Loading...