Standardul de stil al codului sursă DELPHI
Pagina 7 din 12
Clase
Structura corpului clasei
Corpul clasei, atunci când este declarat, este supus următoarei structuri:
- Declarație de câmpuri;
- Declarație de metode;
- Declaratie de proprietati.
Niveluri de acces
Excluzând codul introdus de IDE, directivele de vizibilitate trebuie declarate în următoarea ordine:- Membrii clasei private (ascunse) ( privat);
- Membrii clasei protejate ( protejat);
- Membrii clasei publice ( public);
- Membrii clasei publicati ( publicat)
Astfel, în Object Pascal există patru niveluri de acces pentru membrii clasei: publicat, public, protejat și privat – în ordinea descrescătoare a vizibilității. În mod implicit, nivelul de acces este publicat. În general, membrilor clasei ar trebui să li se acorde cel mai scăzut nivel de acces adecvat pentru acel membru. De exemplu, un membru care este accesibil prin clase din același modul trebuie să aibă nivelul de acces privat. În plus, declarând membrii clasei cu cel mai mic nivel de acces, permiteți compilatorului să profite caracteristici suplimentare pentru optimizare. Pe de altă parte, dacă intenționați să generați ulterior clase copii din clasa dvs., atunci trebuie să utilizați nivelul de acces protejat.
Nu specificați niciodată nivelul de acces public pentru date. Datele trebuie întotdeauna declarate într-o secțiune privată și accesate folosind metode sau proprietăți.
Declarația constructorului
Toate metodele de clasă trebuie să fie ordonate alfabetic. Cu toate acestea, puteți plasa declarațiile de constructor și destructor înaintea tuturor celorlalte metode. Dacă o clasă are mai mult de un constructor și dacă au aceleasi nume, atunci acestea ar trebui aranjate în ordinea numărului crescător de parametriMetode de declarare
Dacă este posibil, declarația metodei ar trebui să fie pe o singură linie:De exemplu:
procedura ImageUpdate(Imagine imagine, infoflags: Integer,
x: număr întreg, y: număr întreg, w: număr întreg, h: număr întreg)
Pagina 5 din 9
Comentarii
Limbajul Object Pascal acceptă două tipuri de comentarii: bloc și o singură linie. Considerațiile generale pentru utilizarea comentariilor ar putea fi:
- Plasați un comentariu lângă începutul modulului pentru a explica scopul acestuia;
- Puneți un comentariu înaintea declarației de clasă;
- Puneți un comentariu înaintea declarației metodei;
- Evitați comentariile evidente: (i:= i + 1 // adăugați unul la i);
- Amintiți-vă că un comentariu înșelător este mai rău decât niciun comentariu;
- Evitați să puneți într-un comentariu informații care ar putea să nu fie adevărate în timp;
- Evitați decorarea comentariilor cu asteriscuri sau alte simboluri;
- Pentru comentarii temporare (nu sunt disponibile), folosiți „TODO”.
Blocați comentariile
Object Pascal acceptă două tipuri de comentarii de bloc. Cel mai frecvent folosit comentariu de bloc este o pereche de acolade: { } . Echipa Delphi preferă să păstreze acest comentariu cât mai simplu posibil și ca o rezervă. Folosiți spații pentru a formata textul din aceste comentarii și nu folosiți asteriscuri „*”. Atunci când înfășurați liniile, trebuie să păstrați indentarea și alinierea
Exemplu din DsgnIntf.pas:
|
Un comentariu de bloc conține întotdeauna informații despre modul: drepturi de autor, data modificării și așa mai departe. Un comentariu de bloc care descrie o metodă trebuie să apară înainte de declararea metodei.
DreaptaAl doilea tip de comentariu de bloc conține două caractere: o paranteză și un asterisc: (* *) . Acest tip de comentariu este folosit în timpul dezvoltării cod sursa. Avantajul său este că acceptă comentarii imbricate, deși comentariile trebuie să fie tipuri diferite. Puteți folosi această proprietate pentru a comenta bucăți mari de cod care conțin alte comentarii:
|
Comentarii pe o singură linie
Un comentariu pe o singură linie este format din // caractere urmate de text de comentariu. Caracterele // trebuie să fie urmate de un spațiu și apoi de text. Comentariile pe o singură linie ar trebui să fie indentate la fel ca codul în care apar. Comentariile pe o singură linie pot fi grupate pentru a forma un comentariu mai mare.
Un comentariu pe o linie poate începe cu linie nouăși poate continua codul pe care îl comentează. În acest caz, trebuie să existe cel puțin un spațiu între cod și comentariu. Dacă codul urmează mai mult de un comentariu, acestea trebuie să fie aliniate în aceeași coloană.
Exemplu de comentariu pe o linie:
|
|
Ar trebui să evitați să utilizați comentarii în cod pentru fiecare linie a modulului.
Dezvoltator al oricărui proiect mare pe Delphi Mai devreme sau mai târziu, te confrunți cu nevoia de a documenta cod, pornind de la comentarii banale la clase/metode și terminând cu un fișier de ajutor cu drepturi depline (html, chm, hlp sau chiar Microsoft Help 2.0). Pentru cei care scriu în Java sau C#, aceasta nu mai este o problemă - au JavaDocȘi castel de nisip. La Delphi situația a fost dificilă până la eliberare 2005 -a versiune, care a adăugat în cele din urmă suport încorporat pentru documentația XML.
Deși chiar și acum, dacă te uiți la codurile sursă ale diferitelor proiecte, nu vei vedea nimic. Cel mai des este folosit stilul javadoc (aparent gratuit DelphiDoc). Iată cum arată comentariile în formatul său:
(** Deschide toate tabelele care sunt marcate pentru deschiderea @param FastOpen Utilizați rutina de deschidere rapidă @return Returns True dacă Ok @see TMainForm ) funcția TMainForm.OpenTables(FastOpen: Boolean): Boolean; începe ... ... sfârşit;
Ajutoarele generate pe baza unor astfel de comentarii par mai mult sau mai puțin decente. Dar spre deosebire de aceeași Eclipsă sau Netbeans, pentru care acest format este nativ, pentru Mediile Delphi aceasta este sălbăticia. Alcătuirea unor astfel de construcții fără nici un ajutor din partea unui IDE este destul de obositoare. Indiferent cât de mult ai încerca, textul „Deschide toate tabelele care sunt marcate pentru deschidere” nu va apărea în sfatul cu instrumente, iar programatorul va trebui să se uite la codul sursă sau să meargă la ajutor de fiecare dată.
Ajutor Insight
Din versiune 2005 , introdus în Delphi tip nou sugestii în editorul de cod - Help Insight. Acum, acestea nu mai sunt acele sfaturi jalnice care erau în versiuni mai vechi.
Ajută Insight în acțiune
Este păcat desigur că CodeGear(și după el Embarcadero) nu sa obosit să facă comentarii detaliate pentru Help Insight pentru toate modulele standard. Probabil, sunt prea leneși să intre în toate codurile sursă, dintre care multe rămân din cele mai vechi aproape fără modificări. versiuni Delphi. Dar nu este asta. Principalul lucru este că această caracteristică funcționează de fapt și, deoarece funcționează, o vom folosi.
Comentarii XML
Acest format este probabil familiar tuturor celor care au întâlnit într-un fel sau altul dezvoltarea în .NET. Acesta este formatul acceptat de Help Insight menționat mai sus și așa arată:
///
Este ușor de ghicit că eticheta rezumat- Acest descrierea metodei, param— descrierea parametrilor; se intoarce— descrierea valorii returnate și vedea— link către o altă descriere. O listă cu toate etichetele poate fi găsită în MSDN (nu am putut găsi nicio informație despre aceasta în paginile de ajutor Delphi 2007 și 2009). Mai mult decât atât, pe lângă etichetele standard, puteți folosi o parte din HTML, de exemplu sau pentru a evidenția comentarii importante. Pentru a scrie astfel de comentarii, este convenabil să utilizați un șablon - tastați „rezumat” în textul programului și faceți clic pe Tasta Tab. În Delphi 2009, nici măcar nu trebuie să tastați singuri cele trei bare oblice de la început - când apăsați Enter, acestea sunt adăugate automat ca în Studio vizual (acesta funcționează și în Delphi 2007 SP3). Este de menționat faptul că comentariile XML pot fi scrise în declarații de clase, proceduri, funcții, tipuri și chiar variabile.
Pentru a vedea comentariile scrise în acțiune, trebuie să mergeți la fereastra de setări ale proiectului (Proiect - Opțiuni) și în fila Compilare, bifați caseta (sau setați-o la Adevărat în Delphi 2009) Generați documentație XML. După fiecare compilare de proiect, Delphi va genera mai multe fișiere XML(unul pe proiect și unul pe modul) care va conține toate comentariile XML. Aceste fișiere pot fi folosite pentru a crea sistem de ajutor. Dar principalul lucru este că acum acest mini-ajutor convenabil va fi afișat în sfaturi cu instrumente:
Din păcate, etichetele HTML din Help Insight nu funcționează, dar toate linkurile funcționează perfect.
Generarea documentației folosind Delphi
În Delphi 2005-2009 există 2 moduri de a crea documentație. Le vom încerca pe amândouă în practică. Primul, și cel mai simplu, este implementat folosind IDE-ul încorporat Împreună. Salvați proiectul și faceți clic pe elementul de meniu View - Model View. Delphi poate întreba dacă să adauge suport de modelare la proiect, selectați da. Se va deschide o fereastră Movel View în care trebuie să selectați proiectul și meniul contextual presa Generați documentație. Va apărea o mică fereastră cu setări (sunt surprinzător de puține), în care vă sfătuiesc imediat să debifați Include diagrameȘi Includeți arborele de navigare. Delphi va depune puțin efort și, după câteva secunde, va produce mai multe pagini HTML.
În mod neașteptat, rezultatul a fost un ajutor clasic care copiază complet javadoc. La început a fost încântare, dar apoi dezamăgire. La o examinare mai atentă, se dovedește că conține multe link-uri obscure inutile, cum ar fi Mod implicit sau globale, și este extrem de incomod de a lucra cu. Toate etichetele
A doua metodă, ca multe lucruri în Delphi, nu este în întregime evidentă - folosim utilitarul furnizat cu IDE-ul XMLDoc. Poate fi găsit în folder Documentele mele\RAD Studio\<версия Delphi>\Demos\XMLDoc. În plus, va trebui să instalați Java SDK (1.4.2 sau o versiune ulterioară), Python (minim 2.3) și (versiunea 6.5.5 pentru Java). După instalare veți avea nevoie adăuga la variabila de sistem „ cale” căile în care sunt instalate Python și Saxon, de exemplu „ C:\Python23\;C\Saxon655\” (acest lucru se face prin „Computerul meu”, iar în el - „ variabile de mediu", căile trebuie adăugate separate prin punct și virgulă). În folderul în care ați extras Saxon, creați fișier BAT Cu nume saxon.bat cu urmatorul continut:
@java-jar "<путь к папке с Saxon>\saxon.jar" %1 %2 %3
Nu este nevoie să-l rulați. Creați un fișier BAT în folderul cu XMLDoc start.bat ca să nu prostesc cu Linie de comanda, și scrieți următoarele în el:
Cls xmldoc.py "<путь к папке с проектом>" pauză
Un exemplu de cale este „C:\Projects\TestProject”. Important: toate căile utilizate nu trebuie să conțină chirilic, altfel XMLDoc va avea probleme cu acesta. Deci, acum totul este gata și puteți rula fișierul start.bat. Dacă totul merge bine, va apărea un folder în folderul proiectului doc, și în ea - finalîn care vor fi depozitate fișiere HTML documentația generată. Iată ce am primit (folosind metoda OpenTables ca exemplu):
De evaluare subiectivă această opțiune arata mai frumos decat primul. Totul pare să fie grozav, dar este agravat de faptul că XMLDoc a tăiat, de asemenea, neglijent legătura
Generarea documentației utilizând Doc-O-Matic Express
Doc-O-Matic- suficient utilitate puternică pentru a crea documentație pentru Bazat pe XMLși comentarii JavaDoc în formatele HTML, CHM și Help 2.0. Dar, din păcate, versiunea sa completă este plătită. Dar nu totul este atât de rău - există o versiune Express (probabil că au prins numele de la Microsoft) și are aproape tot ce ai nevoie. Hai să-l încercăm.
Cu Doc-O-Matic nu va trebui să dansați la fel de mult ca cu XMLDoc, dar nici câteva clicuri nu o vor face. Rulați utilitarul în secțiune Fișiere de proiect faceți clic pe butonul Adăuga, în filtrul de dialog selectați Proiectul Delphi 2007și deschis fișierul necesar proiect. În fila HTML acordați atenție secțiunii Fișiere și foldere— în el puteți specifica folderul în care va fi plasat fișierul de documentație. Salvați setările într-un loc convenabil, de exemplu în fișierul C:\mydoc.dox-express. Acum închideți utilitarul și mergeți la folderul în care este instalat Doc-O-Matic. Creați un fișier BAT cu următoarea linie:
Domexpress.exe -config „HTML”<путь к файлу *.dox-express>"
După executarea acestei comenzi, fișierele de documentație sunt plasate în folderul specificat mai sus și browserul este lansat automat. De exemplu, așa va arăta descrierea metodei:
Din nou, subiectiv, un astfel de ajutor face cea mai favorabilă impresie. Fără puncte în plus navigare convenabilă. Lipsa unui link pe cuvântul „TMainForm” strică puțin impresia, dar cel puțin Doc-O-Matic nu a tăiat-o, spre deosebire de cele două utilități anterioare.
În loc de postfață. Suportul pentru comentarii XML la nivel de editor de cod în Delphi este o caracteristică excelentă și convenabilă și ar trebui să o utilizați. Dar cu generarea documentației, situația este mai complicată: mijloace standard prea crud (și, să fiu sincer, strâmb =) pentru a fi folosit cu ușurință. Există însă o alternativă sub forma Doc-O-Matic Express, care face treaba asta destul de bine. Să sperăm că în curând (poate odată cu lansarea de noi versiuni de Delphi) vor apărea noi utilități mai flexibile.
Limbajul de programare Delphi este destul de simplu de învățat, dar foarte eficient și puternic. Primul lucru cu care trebuie să vă familiarizați sunt comentariile.Comentariile sunt orice text care nu are absolut niciun efect asupra codului programului. Nu se compilează sau nu se lipește niciodată fisier executabil, dar este folosit doar pentru explicațiile codului.
Comentariile pot fi formatate în două moduri:
- tot ce vine după dubla oblică //
, este perceput ca un comentariu
(puteți formata doar o singură linie de comentariu în acest fel); - orice este inclus între acolade ( și ) este, de asemenea, un comentariu
(în acest caz, puteți include câte rânduri doriți în comentariu).
Exemplu de comentariu
// Acesta este un comentariu.Acesta nu mai este un comentariu
(Acesta este din nou un comentariu
si asta)
Acest articol va folosi în mod constant comentarii pentru a explica codul programelor descrise. De aceea a trebuit să-i cunoaștem înainte de a începe să analizăm codul.
Acum sunteți gata să învățați limbajul de programare Delphi. Crea proiect nou. După aceea, accesați editorul de cod. Schița viitorului program a fost deja scrisă pentru tine aici.
Să aruncăm o privire mai atentă la ceea ce este scris aici. Mai jos sunt comentarii detaliate pentru fiecare linie a șablonului creat. Cu toate acestea, ceva lipsește aici pentru ușurința studierii codului programului.
Șablon generat de shell Delphi
unitate Unitl; //Numele modululuiinterfata
utilizări //După acest cuvânt există o listă de module conectate.
Windows, Mesaje, SysUtils, Variante, Clase, Grafică, Controale, Formulare,
Dialoguri;
tip //După aceasta vine declarația de tipuri
TForml = clasă(TForm) //Începe descrierea unui nou obiect TForm. Componentele formularului și evenimentele sunt descrise aici
privat //După acest cuvânt puteți descrie datele private ale obiectului
(Declarații private)
disponibil numai pentru obiectul TForml
public //După acest cuvânt puteți descrie datele deschise ale obiectului
(Declarații publice)
//Sugestie generată de Delphi. Aici puteți descrie variabile și metode,
accesibil din orice alt modul
Sfârşit; //Sfârșitul declarației de tip
var //Declararea variabilelor globale
Forml: TForml; //Acesta descrie variabila Forml a tipului de obiect TForml
implementare
($R *.dfm) //Fișier Connect.dfm (fișier cu date despre obiectele vizuale)
Sfârşit. // se încheie cu un punct - sfârșitul modulului
Dacă ceva rămâne neclar, atunci în procesul de creație programe reale totul va cădea la loc. Nu încerca să-ți amintești totul deodată pentru că este imposibil. Prea mult informație nouă, nesusținut de practică. Încercați să înțelegeți doar sensul programului scris.
Aproape toate rândurile se termină cu „ ; " (punct și virgulă). Acest semn indică sfârșitul unei declarații. Este folosit numai după declarații și nu este niciodată folosit după cuvinte cheie precum
folosește, tip, începe, implementare, privat, public
etc. Ulterior, te vei familiariza cu toate cuvintele cheie, dintre care majoritatea ies în evidență cu aldine. Excepția este imediat vizibilă - ultima din modul Sfârşit, urmată de un punct mai degrabă decât de un punct și virgulă.
Deci, să ne uităm la structura codului. La început este numele modulului. Poate fi orice, dar este același cu numele fișierului (fără a lua în considerare extensia acestuia). Nu este recomandabil să schimbați manual numele modulului. Dacă tot trebuie să îl schimbați, mai întâi salvați modulul cu vechiul nume. Pentru a face acest lucru, selectați comanda de meniu: Fișier | Salvează ca(Fișier | Salvare ca).
Este recomandabil să dați modulelor nume clare. În acest caz, puteți determina după nume ce se află în interiorul modulului cu același nume. Este greu de ghicit ce este în fișierul numit Unitl.pas. De asemenea, este recomandabil să dați fișiere nume care se referă la conținutul lor. De exemplu, forma principală Este mai bine să salvați programele într-un fișier numit MainUnit.pas sau MainModule.pas. În acest caz, modulul și fișierul vor fi numite MainUnit sau MainModule și puteți determina imediat că acesta este formularul principal.
Mai departe conexiune în curs module globale. Toate procedurile, funcțiile, constantele sunt descrise într-un modul și înainte de a utiliza aceste proceduri, trebuie să le conectați. Poate știți că există o funcție. Dar pentru ca compilatorul să știe despre acest lucru, trebuie să specificați modulul în care această funcție este descrisă într-un limbaj pe care compilatorul îl înțelege. De exemplu, trebuie să transformați un număr într-un șir. Delphi are deja funcția IntTostr pentru asta. Este descris în modulul Sysutils. Dacă doriți să utilizați această caracteristică, trebuie să conectați acest modul la modulul Formulare (introduceți numele Sysutils în secțiunea utilizări).
Există patru tipuri de partiții:
- Privat- proprietățile și metodele din această secțiune sunt disponibile numai pentru acest obiect. Alte obiecte nu pot apela aceste metode și proprietăți de citire/scriere;
- Protejat- aceste proprietăți și metode sunt disponibile numai acestui obiect și descendenților săi (obiecte care descind din ale noastre și moștenesc proprietățile sale). Obiectele terțe nu pot accesa proprietățile și metodele stocate aici;
- Public- tot ce este descris aici este disponibil pentru toată lumea;
- Publicat- când scriem propriile componente ale aplicației, în această secțiune vom descrie proprietățile și evenimentele care ar trebui să fie afișate în inspectorul de obiecte. Aceste proprietăți sunt disponibile pentru toată lumea.
După declararea obiectului și a componentelor acestuia, există o descriere a variabilelor globale. Începe după cuvântul cheie varși vine întotdeauna după declararea tipurilor. Trebuie să vă amintiți acest lucru acum, pentru că mai întâi vine secțiunea tip, unde sunt descrise tipurile și apoi var, unde sunt descrise variabilele.
Variabilele globale sunt variabile care sunt stocate pe stivă, create când programul pornește și distruse când programul se iese. Aceasta înseamnă că acestea sunt disponibile oricând și oriunde în timp ce programul rulează.
exemplu de declarare a variabilei globale
var//Declararea variabilelor globaleForml: TForml; //Acesta descrie variabila Forml a tipului de obiect TForml
Acest exemplu declară o variabilă, Forml, de tip TForml. Când obiectul TForml este creat, indicatorul acestuia va fi scris în variabila Form1. Această variabilă este globală și există în timp ce programul rulează, ceea ce înseamnă că poate fi întotdeauna accesată.
Cuvânt cheie implementare Nici deocamdată nu o vom atinge, dar o vom lăsa pentru viitor, când cunoștințele noastre despre Delphi se vor extinde puțin. Ultimul lucru rămas de acoperit în acest capitol este cheia ($R * dfm).
Acoladele pot conține nu numai comentarii, ci și comutatoare ale compilatorului. Ele diferă prin faptul că arată ca ($Letter Parameter]. Litera - indică tipul de cheie. În cazul nostru, litera este folosită R. Această cheie indică faptul că trebuie să includeți fișierul de resurse în în acest caz, .dfm fișier (fișier cu date despre obiectele vizuale) cu același nume ca și numele modulului. Dacă numele modulului Unitatea principala, atunci trebuie să schimbați această cheie în ($R Unitatea principala.dfm). Cheie R- aceasta este singura cheie care va fi necesară pentru moment.
Orice codul programuluiîn Delphi este între început și sfârșit. Cuvânt cheie ÎNCEPEînseamnă începutul codului, a Sfârşit- Sfârşit. De exemplu, când scrieți o procedură, mai întâi trebuie să scrieți numele acesteia (vom vorbi despre cum să faceți acest lucru mai târziu), apoi să includeți codul acesteia între parantezele operatorului de început și de sfârșit.
Pe baza materialelor de șantier
