• Acasă
  • Despre noi
  • Autori
  • Mărturii
  • Arhivă
  • Trimite Articol
  • Contact

WORLDIT

Lumea în 1 și 0.

  • Știri
    • Tehnologie
    • Tehnologie mobilă
    • Securitate
    • Developers
    • Știință
    • Benzi desenate
    • Jocuri
    • Intern
  • Tehnic
    • Browser
    • C#
    • C/C++
    • Challenge
    • HTML/CSS
    • Javascript, Ajax, jQuery
    • Open Source
    • PHP
    • Python
    • Securitate IT
    • Socializare
    • WordPress
    • Altele
  • Recenzii
  • Interviuri
  • Evenimente

phpDocumentor : cum să-ţi documentezi şi să asiguri calitatea proiectelor PHP?

7
  • Publicat de Andrei Avădănei
  • în Open Source · PHP · Tehnic
  • — 27 iul., 2011 at 10:50 am

Eu sunt unul dintre adepţii documentării proiectelor pentru că am realizat (şi nu sunt singurul) că o documentaţie bună a codului ne permite ulterior să trecem prin lucrări realizate în urmă cu săptămâni, luni sau chiar ani ca şi cum ar fi fost cu o săptămână înainte de dezvoltare(bine, poate două).

Da, majoritatea dintre noi avem şi scuze pentru care nu facem asta :

• documentarea codului nu este cerută de client
• nu avem timp, prea multe lucruri de făcut într-un timp foarte scurt
• prea multă muncă şi nimeni nu analizează codul mai târziu
• de ce aş face asta?
• avem o taxa suplimentară pentru documentaţie dar în general clienţii refuză oferta
• etc. etc. etc.


Există mereu scuze pentru treaba aceasta, unele mai originale decât altele. Totuşi, tu ca şi dezvoltator dintr-o firmă sau ca manager al uneia doreşti să atragi cât mai mulţi clienţi. Mai mulţi clienţi sunt atraşi de proiecte de calitate şi de atenţia la detalii. Proiectele de calitate şi atenţia la detalii pot fi subliniate printr-un raport. În raport ar putea fi inclusă şi prezenţa comentariilor din cod ce permit revizuirea regulată mult mai eficientă a codului. Toate acestea îţi aduc mai mulţi bani.

Mai mult decât atât, de multe ori firmele îşi construiesc propriile engine-uri, unelte şi frameworkuri, care de care mai complexe şi utile. Totuşi, dinamismul unei firme implică şi sosirea unor noi dezvoltatori, la fel şi plecare altora. Cum puteţi menţine actualizate aceste aplicaţii interne dacă un dezvoltator nou nu are habar de cum sunt lucrate? Întradevăr, vă puteţi afirmand că dacă repsectivul se pricepe atât de bine în domeniul său ar trebui să înţeleagă. Perfect adevărat, dar lucrul acesta s-ar întâmpla de câteva ori mai încet, deci dumneavoastră, ca reprezentant al firmei veţi pierde nişte bani.

Cum documentezi proiectul tău PHP?

Scrierea unei documentaţii nu este chiar atât de dificilă pe cât unii îşi imaginează şi mai ales, nu necesită un efort prea mare, dar bucuria pe care o veţi avea la revizuirea codului va fi imensă. Pentru documentarea bibliotecilor, claselor şi funcţiilor ar trebui să folosiţi nişte şabloane special predefinite pentru a putea construi la sfârşit documentaţia.

Spre exemplu, un şablon pentru o bibliotecă de clase ar putea arăta astfel :

<?php
/**
 * Biblioteca mea geniala
 *
 * Aceasta biblioteca de clase vine cu functii suplimentare
 * pentru framework x.y.z, compatibil pana la versiunea v.05.
 *
 * @category My
 * @license Copyright 2011 © WorldIT.info, Inc. - All rights reserved
 */

Ceva asemănător puteţi folosi şi pentru descrierea claselor.

/**
 * Clasa_mea_super_geniala
 *
 * Aceasta clasa ma ajuta sa fac clatite v2.0 in 
 * frameworkul folosit de companie.
 *
 * @package Clasa_mea
 * @subpackage Clasa_mea_super_geniala
 * @version $Id:$
 */
class My_Amazing_Component_Class
{
}

La fel, pentru funcţii.

/**
 * Pentru a determina pozitia intr-o harta 2D
 * avem nevoie de latitudine si longitudine.
 *
 * @param float $latitude Latitudinea pozitiei.
 * @param float $longitude Longitudinea pozitiei.
 * @return string Un url catre pozitia respectiva de pe harta.
 * @throws OutOfBoundsException cand valorile sunt invalide.
 */
public function findTheSpot($latitude, $longitude)
{
}

Cum sa construiesti documentatia automata?

Dacă ai finalizat proiectul, ai scris şi comentarii, nu ne rămâne decât să generăm documentaţia folosind un API pentru acest lucru. Există unelte foarte promiţătoare precum Doxygen, DocBlox, phpdocgen şamd. Totuşi, populară rămâne în continuare phpDocumentor, o unealtă simplu de folosit ce cu ajutorul a câţiva parametri reuşeşte să genereze documentaţii de înaltă calitate.

 
  
user@server $: phpdoc \
  -o HTML:frames:earthli \
  -ric docs/README.txt \
  -ti "phpDocumentor Example" \
  -dc MyCompany \
  -dn My_Amazing \
  -d application/models,application/forms,library/My \
  -i *.phtml \
  -t docs/api

Explicaţia parametrilor :

-o HTML:frames:earthli defineşte template-ul ce va fi folosit, în acest exemplu e folosit earthli
-ric docs/README.txt defineşte fişierele README, INSTALL şi CHANGELOG
-ti „PHPDocumentor Example” titltul
-dc MyCompany stabileşte categoria by default dacă nu este niciuna pusă la dispoziţie
-dn My_Amazing stabileşte pachetul default, la fel, dacă lipseşte definiţia unuia
-d application/models,application/forms,library/My defines lista directoarele ce conţin fişiere php ce trebuie documentate
-i *.phtml defineşte fişiere ce ar trebui să fie ignorate când se realizează documentaţia
-t docs/api defineşte locaţia unde ar trebui salvată documentaţia generată

Rezultatul final

O documentaţie elegantă a proiectului.

Etichete: comentarii in phpcum sa-ti documentezi proiectul phpde ce as documenta proiectul phpdespre comentarii phpdocumentarea proiectului phpPHPphpdocumentatorphpDocumentortutorial php

— Andrei Avădănei a scris 1246 articole

Andrei scrie pe worldit.info din vara lui 2011. Este fondatorul Asociatiei Centrul de Cercetare in Securitate Informatica din Romania - CCSIR si coordoneaza DefCamp, cea mai importanta conferinta de securitate informatica & hacking din Europa Centrala si de Est. Andrei ofera in cadrul Bit Sentinel servicii de securitate informatica, penetration testing, security management, recuperarea de pe urma unui atac cibernetic, training-uri si workshop-uri.

  • Articolul anterior Username.ro – verifică disponibilitatea unei identităţi pe canalele sociale
  • Articolul următor MS-DOS, un pionier al sistemelor de operare grafice, a împlinit 30 de ani

7 Comentarii

  1. Roland spune:
    iulie 27, 2011 la 12:46 pm

    Dude, se numeste phpDocumentor, nu phpDocumentator :)))
    De altfel, eu prefer doxygen pentru ca stie si alte limbaje de programare, nu doar PHP

  2. Marian spune:
    iulie 27, 2011 la 12:52 pm

    Foarte interesant articolul. Într-adevăr sunt nişte detalii esenţiale de care foarte mulţi nu ţin cont.
    Sugerez pe viitor un articol despre uneltele de integrare, precum Sonar şi Jenkins. Ar fi mai mult decât binevenit.

    Mulţumim încă o dată pentru articol 🙂

  3. Andrei Avădănei spune:
    iulie 27, 2011 la 1:22 pm

    @Roland Thanks! Nu ma trezisem inca in clipa respectiva. :-)) Da, am lucrat si cu doxygen dar de el voi discuta cu alta ocazie.

    @Marian Multumesc pentru sugestii. Vad cum stau cu timpul si poate scriu ceva despre ele. 🙂

  4. Dinu spune:
    iulie 27, 2011 la 6:49 pm

    Ai uitat sa mentionezi un alt aspect important (desi nu stiu cat de mult se aplica la php). Documentarea codului duce la posibilitatea refolosirii lui intr-un alt proiect. De exemplu cum ai tu clasa ta cu functii pentru harti 2d, o poti adauga ca librari in zend framework si cine stie cand ai un proiect la care ai nevoie de asa ceva. Si mai indicat e sa imparti libraria in sub-librarii (exemplu google-api pentru maps, geometrie 2d pentru calcule, etc). O sa ajungi ca la orice proiect nou ai sa refolosesti cod din proiectele vechi. Asta inseamna un client fericit pentru ca te-ai miscat mai rapid si mai multi bani pentru tine (ca ai parte de proiect deja facuta).

  5. Roland spune:
    iulie 27, 2011 la 8:13 pm

    @Dinu: Nu vad de ce documentarea codului duce la refolosirea lui. Daca ai memorie eidetica sau rabdare sa te mai uiti peste cod, poti sa il refolosesti si daca nu e documentat

  6. Dinu spune:
    iulie 28, 2011 la 1:54 pm

    @Roland: Ce zici tu e valabil pentru proiecte mici spre foarte mici. Cand refolosesti cod trebuie neaparat sa stii daca are posibile limitari, tipuri de teste facute, formatul inputului, formatul outputului, complexitatea, etc. Nu te intereseaza codul in sine ca nu ma refeream la copy-paste.

  7. Roland spune:
    iulie 28, 2011 la 3:28 pm

    @Dinu: Memoria eidetica inseamna ca nu uiti nimica ce ai vazut o data, deci nu ai nevoie de documentatie 😛
    Lasand gluma la o parte, inteleg la ce te referi, si sunt de acord ca documentatia e necesara, dar nu cred ca fara documentatie nu se poate refolosi o bucata de cod.


  • Facebook

    WorldIT.info
  • Ultimele Atacuri Cibernetice din Romania – RO Hacked

    [wp_rss_retriever url="https://rohacked.bit-sentinel.com/feed/" excerpt="none" items="5" read_more="false" new_window="true" thumbnail="false" cache="0"] RO Hacked este registrul atacurilor cibernetice din România.
  • Caută

  • Articole Recomandate

    • Recent Posts
    • Tags
    • Număr record de participanți la DefCamp 2015, cel mai important eveniment dedicat securității cibernetice din Europe Centrala si de Estdecembrie 2, 2015
    • La DefCamp 2015 vei afla prin ce tehnici pot fi evitate măsurile de securitate ale sistemelor informatice criticeoctombrie 16, 2015
    • Ultima sansa sa rezervi bilete de tip Early Bird la DefCamp 2015septembrie 1, 2015
    • 15 sfaturi despre cum poti deveni un programator bun venite de la specialisti romaniaugust 4, 2015
    • algoritmica Android antivirus Apple Avadanei Andrei benzi desenate BitDefender blog browser C++ Chrome concurs eveniment Facebook Firefox Google google chrome hacking html5 infografic informatica internet Internet Explorer IT javascript linux Microsoft Mozilla Firefox online PHP programare retea sociala review Romania securitate Tehnologie Twitter web Windows Windows 7 Wordpress WorldIT worldit.info Yahoo! YouTube
  • februarie 2021
    L Ma Mi J V S D
    1234567
    891011121314
    15161718192021
    22232425262728
    « dec.    
  • Link-uri Sponsorizate

    • laptop second hand

    • Calculatoare Second Hand

    • cod voucher pc garage

  • Home
  • Tehnic
  • Open Source
  • phpDocumentor : cum să-ţi documentezi şi să asiguri calitatea proiectelor PHP?
  • Important

    • Bit Sentinel
    • Centrul de Cercetare în Securitate Informatică din România
    • DefCamp
  • Prieteni

    • BetiT.ro
    • bijuterii handmade
    • Computerica | Resurse gratuite PC
    • Descopera.org
    • Gadgeturi si IT – Giz.ro
  • Prieteni

    • PC – Config
    • RO Hacked
    • Stiri IT

Copyright © 2009-2014 WORLDIT. Toate drepturile Rezervate.
Termeni și condiții | Contact | Licența Creative Commons