Documentația unui mic proiect de programare pentru cel care îl preia

Cine preia un proiect mic de programare are nevoie de patru lucruri: un README clar, instrucțiuni de instalare, o hartă a codului și lista deciziilor importante. Cu ele, un dezvoltator nou poate porni proiectul în câteva ore, nu în câteva zile. Pe Dan Neamtu’, blog personal cu teme diverse, găsești și alte sfaturi practice.

Începe cu README-ul

Fișierul README este prima pagină pe care o deschide cineva. Scrie în el, în câteva rânduri, ce face proiectul, pentru cine este făcut și ce tehnologii folosește. Adaugă pașii de instalare și de rulare, exact în ordinea în care trebuie făcuți, și un exemplu minim care arată că totul funcționează.

Ce trebuie să conțină documentația

• cerințele de mediu: versiuni de limbaj, baze de date, variabile de configurare;
• structura folderelor și rolul fiecărei părți;
• modul de rulare a testelor, dacă există;
• procedura de publicare (deploy);
• conturile și serviciile externe folosite, fără parole în text.

Parolele și cheile nu se scriu în documentație. Indică doar locul în care sunt păstrate și cine le poate oferi.

Explică de ce, nu doar ce

Codul arată ce se întâmplă, dar nu spune de ce s-a ales o soluție. Notează deciziile care nu sunt evidente: de ce există o anumită limitare, ce alternativă ai încercat și ai abandonat, ce probleme cunoscute au rămas. Câteva rânduri de acest fel salvează ore de cercetare.

Comentarii utile în cod

Comentează intenția, nu repetarea codului. Un comentariu de genul „adună două numere” nu ajută pe nimeni. Un comentariu care spune „rotunjim în sus, pentru că factura nu acceptă fracțiuni” este exact ce contează. Denumirile clare ale funcțiilor și variabilelor reduc, de altfel, nevoia de comentarii.

Mică hartă a codului

Fă o listă scurtă cu fișierele sau modulele principale și cu rolul fiecăruia: unde pornește aplicația, unde se află logica de afaceri, unde se păstrează configurările. Dacă proiectul are o bază de date, adaugă o schemă simplă a tabelelor și a relațiilor dintre ele. Chiar și o imagine desenată de mână, fotografiată și atașată, este mai bună decât nimic.

Testează documentația pe cineva nou

Cea mai bună verificare este să rogi un coleg să pornească proiectul doar după instrucțiunile scrise. Fiecare întrebare pe care o pune indică un loc în care documentul trebuie îmbunătățit. Dacă nu ai un coleg, fă testul tu, pe un calculator curat, după câteva săptămâni.

Predarea propriu-zisă

Fixează o scurtă discuție de predare, în care parcurgi împreună cu noul responsabil documentul și îi arăți cum rulează aplicația. Lasă o listă cu lucrurile neterminate și cu persoanele de contact, ca să nu fie nevoie să ghicească.

După predare, o pauză binemeritată

Când documentația este gata și proiectul e predat, poți să te relaxezi. Dacă vrei idei de ieșiri și de timp liber, secțiunea Calatorii & timp liber de pe Dan Neamtu’ e un punct de pornire.

Pe scurt

Un README bun, pași de instalare verificați și explicația deciziilor sunt suficiente pentru un proiect mic. Scrie-le cât timp ai încă proiectul în cap. Mai multe subiecte practice găsești oricând pe blogul Dan Neamtu’.