Unii muzicieni pot citi o partitură simfonică și mai mult sau mai puțin „aud” muzica. La fel, unii programatori pot citi codul brut și vizualiza ceea ce face. Dar majoritatea programatorilor au nevoie de comentarii care să-i ajute să înțeleagă ce face codul, în special dacă au scris codul cu câteva luni înainte sau dacă a fost scris de un alt programator.

De asemenea, mulți programatori consideră că este mai ușor să depaneze procedurile dacă au documentat anterior codul lor. Cea mai bună metodă de a vă documenta codul este de a adăuga comentarii la acesta, fie pe măsură ce creați codul, fie după ce l-ați terminat de creat:

Această procedură face acest lucru. Se așteaptă ca aceste date să fie de intrare și să le furnizeze ca ieșire. Această linie face acest lucru.

Și așa mai departe.

Unii experți vă recomandă să vă documentați codul pe măsură ce îl creați în orice procedură în care încercați diverse metode pentru a vă atinge obiectivul. Adăugați comentarii pentru a explica ce acțiune încearcă să realizeze fiecare grup de declarații. După ce procedura a început să funcționeze, parcurgeți codul și ștergeți declarațiile pe care nu le-ați folosit, folosind comentariile pentru a identifica ce secțiuni sunt inutile și care sunt încă utile și lăsând doar comentariile relevante pentru funcționarea codului rămas.

De asemenea, luați în considerare adăugarea de comentarii atunci când modificați o procedură existentă, astfel încât să nu pierdeți evidența modificărilor dvs. După ce procedura funcționează corect, eliminați orice comentarii inutile și schimbați orice comentarii verbale sau neclare.

Alți experți sugerează documentarea codului când ați terminat de scris. Acest lucru vă permite să introduceți doar liniile de comentarii pe care să le lăsați acolo permanent. Acesta este modul de urmat când sunteți destul de sigur de direcția codului atunci când începeți să scrieți procedura, iar procedura are nevoie de doar câțiva indicatori pentru a clarifica codul său odată ce este complet.

Pentru a vă documenta codul, utilizați comentarii prefațate fie cu un apostrof ('), fie cu cuvântul cheie Rem (prescurtarea pentru remarcă).

Puțini programatori mai folosesc Rem. Când încercați să comentați doar o parte a unei linii, apostroful este, de obicei, alegerea mai bună. Dacă alegeți să utilizați cuvântul cheie Rem, va trebui să adăugați două puncte pentru ca acesta să funcționeze (unele instrucțiuni acceptă Rem fără două puncte la sfârșitul lor; altele generează o eroare de compilare):

Rem Aceasta este o linie de comentariu.

  Documents.Add: Rem crearea unui document bazat pe sablonul Normal.dotm

În general, observațiile comentate cu apostrof sunt separate prin câteva spații sau tab-uri de orice declarație pe care o conține linia (ca în a doua linie, aici). Astfel, codul și comentariile sunt mai ușor de citit decât comentariile care folosesc Rem:

   'Aceasta este o linie de comentariu.

   Documents.Add 'crearea unui document bazat pe sablonul Normal.dotm

Este tentant să credeți că nu trebuie să documentați codul, deoarece vă veți putea reaminti ce face. Dar, după ce ați scris mai multe proceduri, probabil că nu vă veți putea aminti. Revenind la o procedură la șase luni după ce ați scris-o, o veți considera la fel de necunoscută ca și cum ar fi scris-o altcineva. Și dacă ați devenit un profesionist VBA, este posibil să vă fie chiar dificil să vizualizați tehnicile stângace pe care le-ați utilizat în acel moment.

Majoritatea programatorilor au o aversiune distinctă pentru documentarea codului lor; pentru unii, neplăcerea documentării este aproape patologică. Puteți vedea de ce: Când scrieți codul, documentați ce face fiecare linie vă încetinește și vă distrage de la scopul principal. Și documentarea după terminarea și testarea codului este o muncă obositoare. În plus, oricine este competent să poată citi codul și să vadă ce face, nu-i așa?

Poate că da, dar luați în considerare acest lucru: este probabil să nu fiți întotdeauna persoana care lucrează cu codul - uneori, alții ar putea lucra și cu acesta și vor aprecia tot ajutorul pe care îl pot obține în înțelegerea scopurilor și comportamentelor sale. De asemenea, codul nu va fi întotdeauna al dvs. - este posibil ca uneori să fie nevoie de depanarea codului scris de alții și, în astfel de cazuri, veți fi recunoscător pentru comentarii.