Această întrebare are deja răspunsuri aici :
Comentarii
Răspuns
Ar trebui să documentați:
și
- ce poate să nu fi evident, cum.
De ce ați optimizat acest bit, pentru ce anume este această comandă rapidă, care este rezultatul pe care îl așteptați, care este cerința, motivul pentru care a fost acolo în primul rând, de unde sunt trimise aceste date, de unde obțineți intrarea, dacă este multi-threaded, explicați modelul, dacă există o bază de date, explicați schema, legăturile, de ce …
Nu documentați ceea ce este evident. În ceea ce privește prezentarea, există multe modalități de a face acest lucru. Îmi plac personal comentariile în linie (eu sunt un tip mai vechi de programator și nu aveam instrumente fanteziste pe atunci – plus eu găsește-l simplu și direct). Dacă doriți ceva fantezist, asigurați-vă că nu vă consumă prea mult din timpul dvs. sau probabil că îl veți abandona în curând.
Comentarii
Răspuns
Citiți propriul cod pe care l-ați scris acum 2 sau mai mulți ani.
Întrebați-vă ce tipuri de lucruri sunt neclare și lăsați-vă să vă zgâriați în cap la citire. Aceste tipuri de lucruri (oricare ar fi acestea, vor fi diferite pentru diferiți programatori) sunt ceea ce doriți să începeți să documentați mai întâi pe orice cod nou pe care îl dezvoltați sau cod vechi pe care îl rescrieți / reutilizați. Orice formatare care vă încetinește înțelegerea , schimbare.
Sau altfel, peste 2 ani …
Răspuns
Un lucru ar trebui include este dependențele. Dacă o funcție se bazează pe ceva de la acolo , atunci doc umentați ce este, unde este acolo și de ce.
Răspuns
Deoarece utilizați PHP, PHPDoc ar fi un loc bun pentru a începe. Puteți construi documentația API în linie în sursă și apoi utilizați același format pentru a scrie tutoriale și documentația utilizatorului. Veți obține, de asemenea, o oarecare flexibilitate în ceea ce privește formatul de ieșire.
Răspuns
Încep mereu să scriu cod scriind mai întâi comentariile mele. Descrieți fluxul programului și veți începe să vă dați seama ce trebuie comentat și ce nu. După ce ați început să scrieți codul, înfrumusețați părțile care necesită explicații suplimentare și rafinați părțile care se autodocumentează.
După ce fiecare clasă, funcție sau metodă este completă, mă întorc și adaug comentarii pentru un generator de documente cum ar fi doxygen sau PHPDoc. Acest lucru vă va oferi documentația API reală.
În funcție de cine mă consumă codul meu, voi scrie o descriere formală a documentului operațional fie în LaTeX, fie în Word.
Răspuns
Oxigenul acoperă majoritatea limbilor. Va trebui să petreceți ceva timp înțelegând sintaxa, dar marea problemă este ce să documentați. Tratați fiecare funcție ca pe o cutie neagră. Documentați ce intră și ce iese. Documentați ce erori captează, dacă argumentele pot fi nule, dacă poate întoarce un nul.
Amintiți-vă, în doar câteva luni nu veți putea afla ce naiba face o funcție. Vă economisiți doar timp.