Comentarii - explicații la codul sursă al programului , situat direct în interiorul codului comentat. Sintaxa comentariilor este definită de limbajul de programare . Din punctul de vedere al compilatorului sau al interpretului , comentariile fac parte din textul programului care nu afectează semantica acestuia. Comentariile nu au niciun efect asupra rezultatului compilării programului sau interpretării acestuia. Pe lângă codul sursă al programului, comentariile sunt folosite și în limbaje de marcare și limbaje de descriere .
Majoritatea experților sunt de acord că comentariile ar trebui să explice intenția programatorului , nu codul; ceea ce poate fi exprimat într-un limbaj de programare nu trebuie comentat - în special, ar trebui să folosiți nume semnificative pentru variabile, funcții, clase, metode și alte entități (consultați Convențiile de denumire ), împărțiți programul în părți ușor de înțeles, depuneți eforturi pentru a face structura clasei și structura bazei de date cât mai ușor de înțeles și transparent posibil, etc. Există chiar o opinie (este urmată în programarea extremă și în alte metodologii flexibile de programare ) că, dacă sunt necesare comentarii pentru a înțelege programul, înseamnă că este prost scris.
Conceptul de programare alfabetizată insistă pe includerea unor astfel de comentarii detaliate și atente în textul programului, încât să devină textul sursă nu numai pentru codul executabil, ci și pentru documentația însoțitoare .
Comentariile sunt adesea folosite pentru a dezactiva temporar o bucată de cod. În C și C++ , unele[ cine? ] recomandă utilizarea directivelor de preprocesor ( #if 0... #endif) în același scop.
Din punct de vedere al sintaxelor, există două tipuri de comentarii. Un comentariu pe mai multe rânduri poate avea orice lungime și este marcat cu caractere speciale la început și la sfârșit (de exemplu, /* */). Unele limbi permit imbricarea comentariilor pe mai multe rânduri, altele nu.
Un comentariu pe o singură linie este marcat cu un caracter special la început (ex //. ) și continuă până la sfârșitul rândului. În mod normal, comentariile pe o linie pot fi imbricate în alte comentarii, cu o singură linie sau mai multe rânduri. Metodele de înregistrare pot fi intercalate; din punct de vedere al semanticii, sunt aceleași.
Un alt fel de comentarii – adnotări – sunt folosite în schițele de dovezi ale corectitudinii programelor. Astfel de comentarii descriu starea computerului când programul, în timpul execuției, ajunge în punctul în care se află comentariul. Un program adnotat se numește program adnotat .
Comentariile formatate special (așa-numitele comentarii la documentație ) sunt folosite pentru a crea automat documentație , în primul rând pentru bibliotecile de funcții sau clase . Pentru a face acest lucru, se folosesc generatoare de documentație , de exemplu, precum javadoc [1] pentru limbajul Java , phpDocumentor pentru PHP [2] , doxygen [3] pentru C și C++ etc.
Comentariile documentației sunt de obicei formatate ca comentarii în stil C cu mai multe linii . În fiecare caz, comentariul trebuie să apară înaintea elementului documentat. Primul caracter dintr-un comentariu (și la începutul liniilor de comentariu) trebuie să fie *. Blocurile sunt separate prin linii goale.
Exemplu de comentariu de documentație
/** * Nume obiect sau descriere scurtă * * Descriere extinsă * * @descriptor_name valoare * @return data_type */În unele medii de programare (de exemplu , Eclipse , NetBeans , Python , Visual Studio ), comentariile documentelor sunt folosite ca un indiciu interactiv asupra interfeței claselor și funcțiilor.
În timpul traducerii, comentariile sunt recunoscute în etapa de analiză lexicală (și astfel sunt considerate simboluri ). Recunoașterea în etapa de preprocesare este costisitoare și chiar plină de erori; includerea comentariilor în diagramele de sintaxă este aproape imposibilă.
Comentariile ar trebui ignorate de compilator, dar în practică nu este întotdeauna cazul. Unele comenzi speciale pentru traducător, care sunt foarte dependente de implementarea limbajului de programare, sunt adesea formatate ca comentarii.
De exemplu, în dialectul Turbo Pascal , pragmas {$I-}și {$I+}sunt folosite pentru a dezactiva și a activa verificarea standard a erorilor I/O. Comentarii speciale similare sunt folosite în limbajul de marcare HTML pentru a indica tipul unui document SGML , foile de stil „escape” și scripturile în JavaScript și VBScript :
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd"> … < STYLE TYPE = "text/css" > <! -- … descrierea stilurilor -- > </ STYLE > … < SCRIPT TYPE = "text/javascript" > <!-- ascunde conținutul scriptului din browsere mai vechi ... Cod script JavaScript // sfârșitul conținutului ascuns --> < / SCRIPT >Unele comentarii pe care programatorii le folosesc în timpul muncii lor. Comentariile de genul acesta sunt utile în special atunci când mai mulți dezvoltatori lucrează la același cod. De exemplu, un comentariu TODO este de obicei folosit pentru a marca o secțiune de cod pe care programatorul o lasă neterminată pentru a reveni la ea mai târziu. Un comentariu FIXME semnalează o eroare care a fost găsită și se decide să fie remediată mai târziu. Comentariul XXX indică o eroare critică găsită, fără a fi remediată a căror activitate ulterioară nu poate fi continuată.