Scrierea documentației pentru cod nu este sarcina cea mai plăcută și plină de bucurie, dar dacă faceți un proiect mare și / sau participați la dezvoltarea echipei, atunci aș spune că este doar un lucru necesar. Dacă aveți multe interfețe, clase, funcții, metode diferite, cu parametri și ieșiri diferite, iar acest lucru trebuie să funcționeze pentru mai mulți dezvoltatori, este minunat să aveți o descriere a tuturor acestor clase, atributele și parametrii acestora și să nu rulați în jurul fiecărui o dată la dezvoltator și să întrebați ce parametru înseamnă acest lucru. Acest lucru nu elimină în nici un fel faptul că numele claselor, metodelor și parametrilor înșiși ar trebui să aibă nume semnificative, dar acest lucru nu este punctul în discuție. Acum vom vorbi despre documentarea codului sursă pe php. Eu folosesc un instrument ca Doxygen în acest scop.
Ce este Doxygen?
Pentru cei care nu știu ce este, o scurtă referință. Așa cum este scris pe site-ul proiectului:
Doxygen este un sistem de documentare cu cod sursă încrucișat care suportă C / C ++, Object-C, Python, Java, IDL, PHP, C #, Fortran, VHDL și, în parte, D.
Acest utilitar este pentru toate platformele importante: Windows / Linux / MacOS; și unii entuziaști chiar l-au portat pe Solaris / OS / 2 / IRIX / FreeBSD. De asemenea, pe site există documentație excelentă atât în format pdf, cât și în format chm. Recomand foarte mult să o citiți.