Øvelse – opret effektive kodekommentarer

13 minutter

I denne øvelse skal du føje noter til din kode og midlertidigt deaktivere visse kodelinjer fra kompilering. Derefter skal du se på, hvordan C#-compileren forstår mellemrum, og hvordan du bruger mellemrum til at øge læsbarheden af din kode.

Hvad er en kodekommentar?

En kodekommentar er en instruktion til compileren om at ignorere alt efter kodekommentarsymbolerne på den aktuelle linje.

// This is a code comment!

Dette virker muligvis ikke nyttigt i starten, men det er nyttigt i tre situationer:

Når du vil skrive en note om hensigten med en kodepassage. Det kan være nyttigt at inkludere kodekommentarer, der beskriver formålet med eller tankeprocessen, når du skriver et særligt udfordrende sæt kodningsinstruktioner. Din fremtidige selv vil takke dig.
Når du midlertidigt vil fjerne kode fra dit program for at prøve en anden fremgangsmåde, men du endnu ikke er overbevist om, at din nye idé fungerer. Du kan kommentere koden, skrive den nye kode, og når du er overbevist om, at den nye kode vil fungere på den måde, du vil have den til, kan du sikkert slette den gamle (kommenteret kode).
Tilføjelse af en meddelelse som TODO at minde dig om at se på en given kodepassage senere. Selvom du skal bruge denne fornuftigt, er det en nyttig tilgang. Du arbejder muligvis på en anden funktion, når du læser en kodelinje, der giver anledning til bekymring. I stedet for at ignorere det nye problem kan du markere det til undersøgelse senere.

Seddel

Kodekommentarer skal bruges til at sige, hvad koden ikke kan. Udviklere opdaterer ofte deres kode, men glemmer at opdatere kodekommentarerne. Det er bedst at bruge kommentarer til idéer på højere niveau og ikke tilføje kommentarer om, hvordan en individuel kodelinje fungerer.

Forbered dit kodemiljø

Dette modul indeholder øvelser, der guider dig gennem processen med at bygge og køre eksempelkode. Du opfordres til at fuldføre disse aktiviteter ved hjælp af Visual Studio Code som dit udviklingsmiljø. Brug af Visual Studio Code til disse aktiviteter hjælper dig med at blive mere fortrolig med at skrive og køre kode i et udviklermiljø, der bruges af fagfolk over hele verden.

Åbn Visual Studio Code.

Du kan bruge Menuen Start i Windows (eller en tilsvarende ressource for et andet operativsystem) til at åbne Visual Studio Code.
Vælg Åbn mappe i menuen Filer i Visual Studio Code.
Gå til mappen Windows Desktop i dialogboksen Åbn mappe .

Hvis du har en anden mappeplacering, hvor du gemmer kodeprojekter, kan du i stedet bruge denne mappeplacering. Til denne træning er det vigtigt at have en placering, der er nem at finde og huske.
Vælg Vælg mappe i dialogboksen Åbn mappe.

Hvis du får vist en sikkerhedsdialogboks, hvor du bliver spurgt, om du har tillid til forfatterne, skal du vælge Ja.
Vælg Ny terminal i menuen Visual Studio Code Terminal.

Bemærk, at mappestien for den aktuelle mappe vises i en kommandoprompt i terminalpanelet. For eksempel:
```
C:\Users\someuser\Desktop>
```
Seddel

Hvis du arbejder på din egen pc i stedet for i en sandkasse eller et hostet miljø, og du har fuldført andre Microsoft Learn-moduler i denne C#-serie, har du måske allerede oprettet en projektmappe til kodeeksempler. Hvis det er tilfældet, kan du springe over næste trin, som bruges til at oprette en konsolapp i mappen TestProject.
Angiv følgende prompt ved kommandoprompten Terminal for at oprette et nyt konsolprogram i en angivet mappe:
```
dotnet new console -o ./CsharpProjects/TestProject
```
Denne .NET CLI-kommando bruger en .NET-programskabelon til at oprette et nyt C#-konsolprogramprojekt på den angivne mappeplacering. Kommandoen opretter mapperne CsharpProjects og TestProject for dig og bruger TestProject som navnet på filen .csproj .

Hvis der vises en meddelelse om, at filerne allerede findes, skal du fortsætte med de næste trin. Du skal genbruge de eksisterende projektfiler.
Udvid mappen CsharpProjects i STIFINDER-visningen.

Du bør kunne se mappen TestProject og to filer, en C#-programfil med navnet Program.cs og en C#-projektfil med navnet TestProject.csproj.
Vælg Åbn mappe i menuen Filer i Visual Studio Code.
I dialogboksen Åbn mappe skal du vælge mappen CsharpProjects og derefter vælge Vælg mappe.
Udvid mappen TestProject i visningen STIFINDER, og vælg derefter Program.cs.
Slet de eksisterende kodelinjer.

Du skal bruge dette C#-konsolprojekt til at oprette, bygge og køre kodeeksempler under dette modul.
Luk terminalpanelet.

Opret og brug kodekommentarer

I denne opgave skal du oprette og fjerne forskellige typer kodekommentarer.

Angiv følgende kode i panelet Visual Studio Code Editor:

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

Hvis du vil ændre din kode med kodekommentarer og -ændringer, skal du opdatere koden på følgende måde:

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.");

Brug et øjeblik på at gennemse dine kommentarer og kodeopdateringer.

Bemærk, at kodekommentarerne bruges til at dokumentere den potentielle ændring, der foretages, og til midlertidigt at deaktivere den gamle meddelelse, mens du tester den nye meddelelse. Dit næste trin er at teste din opdatering. Hvis du er tilfreds med den nye kode, kan du trygt slette den gamle kode, der blev kommenteret. Dette er en sikrere og mere metodisk tilgang til ændring af arbejdskoden, indtil du er overbevist om, at du er klar til at fjerne den permanent.
Klik på Gem i menuen Filer i Visual Studio Code.
Hvis du vil åbne en Terminal på placeringen af mappen TestProject i STIFINDER-visningen, skal du højreklikke på TestProject og derefter vælge Åbn i integreret terminal.
Skriv dotnet run i kommandoprompten Terminal, og tryk derefter på Enter.

Du bør kunne se følgende output:
```
Bob purchased 7 widgets.
```
Hvis du er tilfreds med dine opdateringer, skal du slette den gamle kode, der er kommenteret ud.

Slet kodekommentarerne.

Din kode skal stemme overens med følgende:

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

Hvis du vil anvende en blokkommentar, der kommenterer flere linjer, skal du opdatere koden på følgende måde:
```
/*
string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
*/
```
Blokkommentarer er gode, hvis du har brug for at skrive en lang kommentar eller fjerne mange kodelinjer. Blokkommentarer bruger en /* i begyndelsen af koden og en */ i slutningen. Brug af en blokkommentar er den hurtigste og nemmeste måde at deaktivere tre eller flere kodelinjer på.

Erstat din eksisterende kode med følgende:

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);
}

Seddel

Der er mange C#-begreber i denne kodeliste, som kan være nye for dig. Det er ikke nødvendigt at forstå, hvad koden gør for at forstå, hvordan kommentarer kan hjælpe læserne med at forstå formålet med koden.

Brug et øjeblik på at se, om du kan finde ud af formålet med koden.

I betragtning af kommentarerne kan du muligvis finde ud af, hvad koden gør (under forudsætning af at kommentarerne beskriver den aktuelle tilstand præcist og blev opdateret, efterhånden som koden blev opdateret). Men kan du gætte, hvorfor denne kode findes? Ville det ikke være nyttigt, hvis der var en forklaring øverst i kodefilen, der gav en kontekst og beskrev formålet med den?
Overvej, hvordan du kan forbedre kommentarerne.

Bemærk, at der er to primære problemer med disse kommentarer:
- Kodekommentarerne forklarer unødigt den åbenlyse funktionalitet af individuelle kodelinjer. Disse betragtes som kommentarer af lav kvalitet, fordi de blot forklarer, hvordan C# eller metoderne i .NET Class Library fungerer. Hvis læseren ikke kender disse ideer, kan de slå dem op ved hjælp af learn.microsoft.com eller IntelliSense.
- Kodekommentarerne giver ingen kontekst til det problem, der løses af koden. Disse betragtes som kommentarer af lav kvalitet, fordi læseren ikke får nogen indsigt i formålet med denne kode, især da den er relateret til det større system.

Fjern de eksisterende kommentarer.

Din kode skal stemme overens med følgende:

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);
}

Bemærk, at koden allerede er mindre rodet.

Hvis du vil tilføje en kommentar, der forklarer formålet med din kode på højere niveau, skal du opdatere koden på følgende måde:

/*
  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);
}

En kommentars anvendelighed er subjektiv. I alle spørgsmål, der er relateret til kodelæsbarhed, skal du bruge din bedste dømmekraft. Gør, hvad du synes er bedst for at forbedre klarheden i din kode.

Resumé

De vigtigste elementer i denne øvelse:

Brug kodekommentarer til at give dig selv meningsfulde noter om det problem, som din kode løser.
Brug ikke kodekommentarer, der forklarer, hvordan C# eller .NET Class Library fungerer.
Brug kodekommentarer, når du midlertidigt prøver alternative løsninger, indtil du er klar til at bekræfte den nye kodeløsning, hvorefter du kan slette den gamle kode.
Hav aldrig tillid til kommentarer. De afspejler muligvis ikke kodens aktuelle tilstand efter mange ændringer og opdateringer.

Feedback

Var denne side nyttig?