Dokumentovanje koda

b0ne^
/srv/http/Posts: 22Administrator edited January 9 in PHP

[ Dokumentovanje koda ]

[ Sadrzaj ]
[0] But why
[1] Elementi
[2] Primeri

1) But why?
Dokumentovanje koda je jedna veoma vazna stavka tokom pisanja bilo koje aplikacije ili skripte. Korisno je iz mnogobrojnih razloga, a ja cu navesti neke. Community. Ako se ikada odlucite da objavite kod na internet kako bi ga drugi koristili ili pregledali radi poboljsanja neophodno je imati i dokumentaciju. Razliciti ljudi razmisljaju razlicito i zato je obavezno opisati sta funkcija obavlja, koje parametre ima, cemu koji sluzi, i kako se funkcija ponasa pri izvrasavanju (povratne vrednosti, izuzetci). Cak i da nikada ne objavite kod u nekom trenutku u buducnosti cete se vratiti na taj kod bilo da cisto bacite pogled bilo da nesto iskoristite iz njega. Vremenom ljudi promene malo nacin pisanja i napreduju tako da stari kodovi budu nepregledni i nekvalitetni i posle vam treba dosta vremena kako biste raspoznali sta ste i zasto radilu o tom kodu. Takodje jos jedan od razloga je ako pravite aplikaciju na kojoj ce se nesto nadogradjivati stalno nije lose ni napraviti PDF dokumentaciju radi lakseg rada - postoji mnogo programa koji od dokumentacije iz koda izgenerisu PDF dokumentaciju.

[1] Elementi
Sada kado smo pokrili to zasto je korisno pisati dokumentaciju vreme je da pogledamo neke od elemenata dokumentacije. Dokumentacija se obicno pise na pocetku fajlova, iznad promenljivih i funkcija. Posto kodovi koju zahtevaju dokumentaciju su obicno veceg obima pisani su na OOP nacin, ali i procedularni kodovi se mogu dokumentovati. Evo nekih osnovnih elemenata:

@var - Sluzi za dokumentaciju promenljiva koja nije parametar funkcije
Primer: @var int $age User age

@param - Sluzi za dokumentaciju parametra funkcije, navodimo tip, naziv i opis ukoliko je potreban
Primer: @param string $name User name

@return - Sluzi za dokumentovanje povratne vrednosti funkcije, navodimo tip i opis ukoliko je potreban
Primer: @return array Array containing results from database

@throws - Sluzi za navodjenje izuzetaka (exceptions) koje funkcija baca u slucaju da nesto nije kako treba
Primer: @throws InvalidFileTypeException if the file is not a valid image

@see - Sluzi za navodjenje reference na neku promenljivu/funkciju/klasu
Primer: @see User::getUserInfo()

@package, @author, @version, @copyright - Sluze za navodjenje osnovnih informacija o paketu, mogu se koristiti svi zajedno ili pojedinacno
Primer:
@package Paket
@author lerdi
@version 0.8
@copyright Street

[2] Primeri
Postoji vise standarda po kojima moze da se pise dokumentacija, ja cu demonstrirati samo jedan. Za tipove promenljivih, parametara i povratnih vrednosti dostupni su: puno ime klase, ukljucen namespace ukoliko ga ima, (na primer \Exception, \Datetime ili ukoliko nema namespaceova Exception, Datetime), int (ili integer), string, float, bool (ili boolean), array, resource, null, callable ili neke keywords kao sto su mixed, void, object...
Primeri mislim da su self-explanied tako da necu ulaziti u detalje objasnjavanja

<?php
    /**
     * @param array $image Array containing single or multiple images
     * @param string $path Upload destination
     * @param array $options
     *      $options = [
     *          $options['resize']              => (bool) Whether to resize image
     *          $options['thumbnail']           => (array|bool) Thumbnail dimensions
     *          $options['watermark']           => (bool) Add watermark to image
     *          $options['watermark_image']     => (string|bool) Watermark path
     *          $options[''watermark_position'] => (string) Watermark position
     *      ]
     *
     * @throws Exception if some of the options are invalid
     * @throws Exception if destination path doesn't exists
     * @return array
     */
    public function upload(array $image, string $path, array $options = ['resize' => false, 'thumbnail' => [150, 150], 'watermark' => false, 'watermark_image' => false, 'watermark_position' => 'bottom-right']): array {...}
?>

<?php
    class Validator {
        /**
         * Rules for fields
         * @var array
         */
        protected $rules = [];
        /**
         * Field values
         * @var array
         */
        protected $field_values = [];
?>

<?php
    /**
     * Include all required files
     *
     * @throws \Exception if config.php file doesn't exists
     * @throws \Exception if path location doesn't exists
     * @return void
     */
    private function includeFiles() {...}
?>

<?php
    /**
     * Generate requested view
     *
     * @param string $view View file to be printed
     * @param array $data Data to be forwarded to view
     *
     * @throws Exception if requested view doesn't exists
     * @return string Generated view content
     */
    final public function generate(string $view, array $data = []): string {...}
?>

<?php
    final class Filter {
        /**
         * Whether filters file is included
         * @var bool
         */
        private static $included = false;
?>

If you don't know who I am, then maybe your best course would be to tread lightly.

Sign In or Register to comment.

Welcome

It looks like you're new here. If you want to get involved, click one of these buttons!

Discussions