Exerciții - Crearea de comentarii de cod eficiente

13 minute

În acest exercițiu, veți adăuga note la cod și veți dezactiva temporar anumite linii de cod din compilare. Apoi veți vedea cum înțelege compilatorul C# spațiul alb și cum să utilizați spațiul alb pentru a mări lizibilitatea codului.

Ce este un comentariu de cod?

Un comentariu de cod este o instrucțiune pentru compilator pentru a ignora totul după simbolurile comentariu de cod din linia curentă.

// This is a code comment!

Acest lucru poate să nu pară util la început, însă este util în trei situații:

Atunci când doriți să lăsați o notă despre intenția unui pasaj de cod. Poate fi util să includeți comentarii de cod care descriu scopul sau procesul de gândire atunci când scrieți un set deosebit de dificil de instrucțiuni de codificare. Viitorul tău îți va mulțumi.
Atunci când doriți să eliminați temporar codul din aplicație pentru a încerca o altă abordare, dar nu sunteți convins încă că noua idee va funcționa. Puteți să comentați codul, să scrieți noul cod, iar după ce sunteți convins că noul cod va funcționa așa cum doriți, puteți șterge în siguranță codul vechi (cod comentat).
Adăugarea unui mesaj care vă amintește TODO să priviți un anumit pasaj de cod mai târziu. Deși ar trebui să utilizați acest judicios, este o abordare utilă. Este posibil să lucrați la o altă caracteristică atunci când citiți o linie de cod care vă preocupă. În loc să ignorați noua preocupare, o puteți marca pentru investigație mai târziu.

Notă

Comentariile de cod ar trebui utilizate pentru a spune ce nu poate face codul. Adesea, dezvoltatorii își actualizează codul, dar uită să actualizeze comentariile la cod. Se recomandă să utilizați comentarii pentru idei de nivel superior și să nu adăugați comentarii despre modul în care funcționează o linie de cod individuală.

Pregătește-ți mediul de codare

Acest modul include exerciții care vă ghidează prin procesul de creare și rulare cod eșantion. Sunteți încurajat să finalizați aceste activități utilizând Visual Studio Code ca mediu de dezvoltare. Utilizarea Codului Visual Studio pentru aceste activități vă va ajuta să deveniți mai confortabil să scrieți și să rulați cod într-un mediu de dezvoltator utilizat de profesioniști din întreaga lume.

Deschideți Visual Studio Code.

Puteți utiliza meniul Start Windows (sau resursa echivalentă pentru un alt sistem de operare) pentru a deschide Visual Studio Code.
În meniul Fișier Visual Studio Code, selectați Deschidere folder.
În caseta de dialog Deschidere folder, navigați la folderul Desktop Windows.

Dacă aveți o altă locație de folder în care păstrați proiectele de cod, puteți utiliza acea locație de folder în schimb. Pentru această instruire, lucrul important este să aveți o locație ușor de găsit și de reținut.
În caseta de dialog Deschidere folder, selectați Selectare folder.

Dacă vedeți o casetă de dialog de securitate care vă întreabă dacă aveți încredere în autori, selectați Da.
În meniul Terminal Visual Studio Code, selectați Terminal nou .

Observați că o linie de comandă din panoul Terminal afișează calea folderului pentru folderul curent. De exemplu:
```
C:\Users\someuser\Desktop>
```
Notă

Dacă lucrați pe propriul PC, nu într-un sandbox sau într-un mediu găzduit și ați finalizat alte module Microsoft Learn din această serie C#, este posibil să fi creat deja un folder de proiect pentru eșantioane de cod. În acest caz, puteți trece peste pasul următor, care este utilizat pentru a crea o aplicație consolă în folderul TestProject.
În linia de comandă Terminal, pentru a crea o aplicație consolă nouă într-un folder specificat, introduceți următoarea solicitare:
```
dotnet new console -o ./CsharpProjects/TestProject
```
Această comandă .NET CLI utilizează un șablon de program .NET pentru a crea un nou proiect de aplicație consolă C# în locația de folder specificată. Comanda creează folderele CsharpProjects și TestProject pentru dvs. și utilizează TestProject ca nume al fișierului .csproj .

Dacă se afișează un mesaj care vă spune că fișierele există deja, continuați cu pașii următori. Veți reutiliza fișierele de proiect existente.
În vizualizarea EXPLORER, extindeți folderul CsharpProjects .

Ar trebui să vedeți folderul TestProject și două fișiere, un fișier program C# denumit Program.cs și un fișier de proiect C# numit TestProject.csproj.
În meniul Fișier Visual Studio Code, selectați Deschidere folder.
În caseta de dialog Deschidere folder , selectați folderul CsharpProjects , apoi selectați Selectare folder.
În vizualizarea EXPLORER, extindeți folderul TestProject, apoi selectați Program.cs.
Ștergeți liniile de cod existente.

Veți utiliza acest proiect de consolă C# pentru a crea, a construi și a rula eșantioane de cod în timpul acestui modul.
Închideți panoul Terminal.

Crearea și utilizarea comentariilor de cod

În această activitate, veți crea și elimina diverse tipuri de comentarii de cod.

În panoul Visual Studio Code Editor, introduceți următorul cod:

string firstName = "Bob";
int widgetsSold = 7;
Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");

Pentru a modifica codul cu comentarii de cod și revizuiri, actualizați codul după cum urmează:

string firstName = "Bob";
int widgetsPurchased = 7;
// Testing a change to the message.
// int widgetsSold = 7;
// Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

Luați un minut pentru a revizui comentariile și actualizările de cod.

Observați că comentariile de cod sunt utilizate pentru a documenta modificarea potențială efectuată și pentru a dezactiva temporar mesajul vechi în timp ce testați noul mesaj. Următorul pas va fi să testați actualizarea. Dacă sunteți mulțumit de noul cod, puteți șterge în siguranță codul vechi care a fost comentat. Aceasta este o abordare mai sigură și mai metodică a modificării codului de lucru până când sunteți convins că sunteți gata să îl eliminați definitiv.
În meniul Fișier cod Visual Studio, faceți clic pe Salvare.
În vizualizarea EXPLORER, pentru a deschide un Terminal la locația folderului TestProject, faceți clic dreapta pe TestProject, apoi selectați Deschidere în Terminal integrat.
În linia de comandă Terminal, tastați run dotnet , apoi apăsați pe Enter.

Ar trebui să vedeți următoarea ieșire:
```
Bob purchased 7 widgets.
```
Din nou, dacă sunteți mulțumit de actualizări, ștergeți codul vechi care a fost comentat.

Ștergeți comentariile de cod.

Codul dvs. ar trebui să corespundă următoarelor:

string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");

Pentru a aplica un comentariu de blocare care comentează pe mai multe linii, actualizați codul după cum urmează:
```
/*
string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
*/
```
Blocarea comentariilor este foarte bună dacă trebuie să scrieți un comentariu lung sau să eliminați mai multe linii de cod. Blocarea comentariilor utilizează un /* la începutul codului și un */ la sfârșit. Utilizarea unui comentariu de blocare este cea mai rapidă și mai simplă modalitate de a dezactiva trei sau mai multe linii de cod.

Înlocuiți codul existent cu următoarele:

Random random = new Random();
string[] orderIDs = new string[5];
// Loop through each blank orderID
for (int i = 0; i < orderIDs.Length; i++)
{
    // Get a random value that equates to ASCII letters A through E
    int prefixValue = random.Next(65, 70);
    // Convert the random value into a char, then a string
    string prefix = Convert.ToChar(prefixValue).ToString();
    // Create a random number, pad with zeroes
    string suffix = random.Next(1, 1000).ToString("000");
    // Combine the prefix and suffix together, then assign to current OrderID
    orderIDs[i] = prefix + suffix;
}
// Print out each orderID
foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

Notă

Există multe concepte C# în această listare de cod care pot fi noi pentru dvs. Nu este necesar să înțelegeți ce face codul pentru a aprecia modul în care comentariile pot ajuta cititorii să înțeleagă scopul codului.

Faceți un minut pentru a vedea dacă vă dați seama de scopul codului.

Având în vedere comentariile, este posibil să reușiți să vă dați seama ce face codul (presupunând că comentariile descriu corect starea curentă și au fost actualizate pe măsură ce a fost actualizat codul). Dar puteți ghici de ce există acest cod? Nu ar fi util dacă a existat o explicație în partea de sus a fișierului de cod care a furnizat un anumit context și a descris scopul său?
Luați în considerare modul în care ați îmbunătăți comentariile.

Observați că există două probleme principale cu aceste comentarii:
- Comentariile de cod explică inutil funcționalitatea evidentă a liniilor individuale de cod. Acestea sunt considerate comentarii de calitate scăzută, deoarece explică doar modul în care funcționează C# sau metodele bibliotecii de clasă .NET. Dacă cititorul nu este familiarizat cu aceste idei, le poate căuta utilizând learn.microsoft.com sau IntelliSense.
- Comentariile de cod nu oferă niciun context problemei rezolvate de cod. Acestea sunt considerate comentarii de calitate scăzută, deoarece cititorul nu are nicio perspectivă asupra scopului acestui cod, mai ales că se referă la sistemul mai mare.

Eliminați comentariile existente.

Codul dvs. ar trebui să corespundă următoarelor:

Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

Observați că codul este deja mai puțin aglomerat.

Pentru a adăuga un comentariu care explică scopul de nivel superior al codului, actualizați codul după cum urmează:

/*
  The following code creates five random OrderIDs
  to test the fraud detection process.  OrderIDs 
  consist of a letter from A to E, and a three
  digit number. Ex. A123.
*/
Random random = new Random();
string[] orderIDs = new string[5];

for (int i = 0; i < orderIDs.Length; i++)
{
    int prefixValue = random.Next(65, 70);
    string prefix = Convert.ToChar(prefixValue).ToString();
    string suffix = random.Next(1, 1000).ToString("000");

    orderIDs[i] = prefix + suffix;
}

foreach (var orderID in orderIDs)
{
    Console.WriteLine(orderID);
}

Utilitatea unui comentariu este subiectivă. În toate aspectele legate de lizibilitatea codului, ar trebui să utilizați cea mai bună hotărâre. Faceți ceea ce credeți că este mai bine să îmbunătățiți claritatea codului dvs.

Recapitula

Principalele decolări din acest exercițiu:

Utilizați comentarii de cod pentru a vă lăsa note semnificative despre problema pe care o rezolvă codul.
Nu utilizați comentarii de cod care explică modul în care funcționează C# sau Biblioteca de clasă .NET.
Utilizați comentarii de cod atunci când încercați temporar soluții alternative până când sunteți gata să vă comiteți la noua soluție de cod, moment în care puteți șterge codul vechi.
Nu aveți niciodată încredere în comentarii. Acestea pot să nu reflecte starea curentă a codului după multe modificări și actualizări.

Feedback

Această pagină a fost utilă?