Övning – Skapa effektiva kodkommenteringar

13 minuter

I den här övningen lägger du till anteckningar i koden och inaktiverar tillfälligt vissa kodrader från kompilering. Sedan ska du titta på hur C#-kompilatorn förstår blanksteg och hur du använder blanksteg för att öka kodens läsbarhet.

Vad är en kodkommentar?

En kodkommentar är en instruktion till kompilatorn att ignorera allt som står efter kodkommentarssymbolerna på den aktuella raden.

// This is a code comment!

Kanske ser det här inte så användbart ut vid första anblicken, men det kommer till pass i tre situationer:

När du vill göra en anteckning om avsikten med ett kodavsnitt. Det kan vara bra att inkludera kodkommentorer som beskriver syftet eller tankeprocessen när du skriver en särskilt utmanande uppsättning kodningsinstruktioner. Du kommer att tacka dig själv framöver.
När du vill ta bort kod från ditt program tillfälligt och prova en annan metod men ännu inte är övertygad om att din nya idé kommer att fungera. Du kan kommentera bort koden och skriva ny kod. När du är övertygad om att den nya koden fungerar korrekt kan du ta bort den gamla bortkommenterade koden.
Lägg till ett meddelande i stil med TODO för att påminna dig om att titta på ett visst kodavsnitt senare. Även om du bör använda detta omdömesgillt är det en användbar metod. Du arbetar kanske med en annan funktion och läser en kodrad som ser misstänkt ut. I stället för att ignorera det kan du markera kodraden och titta på den senare.

Kommentar

Kodkommentar bör användas för att säga vad koden inte kan. Utvecklare uppdaterar ofta sin kod men glömmer att uppdatera kodkommentarerna. Det är bäst att använda kommentarer för idéer på hög nivå i stället för att förklara hur en enskild kodrad fungerar.

Förbereda din kodningsmiljö

Den här modulen innehåller övningar som vägleder dig genom processen att skapa och köra exempelkod. Du uppmanas att slutföra dessa aktiviteter med Visual Studio Code som utvecklingsmiljö. Genom att använda Visual Studio Code för dessa aktiviteter kan du bli mer bekväm med att skriva och köra kod i en utvecklarmiljö som används av proffs över hela världen.

Öppna Visual Studio Code.

Du kan använda Windows Start-menyn (eller motsvarande resurs för ett annat operativsystem) för att öppna Visual Studio Code.
På menyn Visual Studio Code-fil väljer du Öppna mapp.
I dialogrutan Öppna mapp navigerar du till mappen Windows Desktop.

Om du har en annan mappplats där du behåller kodprojekt kan du använda den mappplatsen i stället. För den här utbildningen är det viktigt att ha en plats som är lätt att hitta och komma ihåg.
I dialogrutan Öppna mapp väljer du Välj mapp.

Om du ser en säkerhetsdialogruta som frågar om du litar på författarna väljer du Ja.
Välj Ny terminal på visual Studio Code-terminalmenyn.

Observera att en kommandotolk i terminalpanelen visar mappsökvägen för den aktuella mappen. Till exempel:
```
C:\Users\someuser\Desktop>
```
Kommentar

Om du arbetar på din egen dator i stället för i en sandbox-miljö eller en värdbaserad miljö och du har slutfört andra Microsoft Learn-moduler i den här C#-serien kanske du redan har skapat en projektmapp för kodexempel. I så fall kan du hoppa över nästa steg, som används för att skapa en konsolapp i mappen TestProject.
I terminalkommandot anger du följande fråga för att skapa ett nytt konsolprogram i en angiven mapp:
```
dotnet new console -o ./CsharpProjects/TestProject
```
Det här .NET CLI-kommandot använder en .NET-programmall för att skapa ett nytt C#-konsolprogramprojekt på den angivna mappplatsen. Kommandot skapar mapparna CsharpProjects och TestProject åt dig och använder TestProject som namnet på filen .csproj .

Om ett meddelande visas som talar om för dig att filerna redan finns fortsätter du med nästa steg. Du återanvänder de befintliga projektfilerna.
I utforskarvyn expanderar du mappen CsharpProjects .

Du bör se mappen TestProject och två filer, en C#-programfil med namnet Program.cs och en C#-projektfil med namnet TestProject.csproj.
På menyn Visual Studio Code-fil väljer du Öppna mapp.
I dialogrutan Öppna mapp väljer du mappen CsharpProjects och väljer sedan Välj mapp.
I explorer-vyn expanderar du mappen TestProject och väljer sedan Program.cs.
Ta bort de befintliga kodraderna.

Du kommer att använda det här C#-konsolprojektet för att skapa, skapa och köra kodexempel under den här modulen.
Stäng terminalpanelen.

Skapa och använda kodkommentar

I den här uppgiften skapar och tar du bort olika typer av kodkommentar.

I panelen Visual Studio Code-redigeraren anger du följande kod:

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

Om du vill ändra koden med kodkommentar och revisioner uppdaterar du koden på följande sätt:

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

Ta en minut att granska dina kommentarer och koduppdateringar.

Observera att kodkommentarna används för att dokumentera den potentiella ändringen som görs och för att tillfälligt inaktivera det gamla meddelandet när du testar det nya meddelandet. Nästa steg är att testa uppdateringen. Om du är nöjd med den nya koden kan du på ett säkert sätt ta bort den gamla koden som har kommenterats ut. Det här är en säkrare och mer metodisk metod för att ändra arbetskod tills du är övertygad om att du är redo att ta bort den permanent.
Klicka på Spara på Visual Studio Code-menyn.
Högerklicka på TestProject för att öppna en terminal på mappen TestProject och välj sedan Öppna i integrerad terminal.
I terminalkommandot skriver du dotnet run och trycker sedan på Retur.

Du bör se följande utdata:
```
Bob purchased 7 widgets.
```
Om du är nöjd med dina uppdateringar tar du bort den gamla koden som har kommenterats ut.

Ta bort kodkommentarna.

Din kod bör matcha den här:

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

Om du vill använda en blockkommentare som kommenterar ut flera rader uppdaterar du koden på följande sätt:
```
/*
string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
*/
```
Blockera kommentarer är bra om du behöver skriva en lång kommentar eller ta bort många rader med kod. Blockera kommentarer använder en /* i början av koden och en */ i slutet. Att använda en blockkommentare är det snabbaste och enklaste sättet att inaktivera tre eller flera kodrader.

Ersätt din befintliga kod med följande:

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

Kommentar

Det finns många C#-begrepp i den här kodlistan som kan vara nya för dig. Du behöver inte förstå vad koden gör för att se hur kommentarer hjälper läsarna att förstå kodens syfte.

Ta en minut för att se om du kan ta reda på syftet med koden.

Med hjälp av kommentarerna kan du kanske lista ut vad koden gör (förutsatt att kommentarerna korrekt beskriver det aktuella tillståndet och uppdaterades i takt med kodändringarna). Men kan du gissa varför den här koden finns? Skulle det inte vara användbart om det fanns någon förklaring överst i kodfilen som gav en viss kontext och beskrev dess syfte?
Fundera på hur du skulle förbättra kommentarerna.

Observera att det finns två huvudsakliga problem med dessa kommentarer:
- Kommentarerna förklarar självklara syften med enskilda kodrader i onödan. De här kommentarerna anses vara av låg kvalitet eftersom de bara förklarar hur C# eller metoderna i .NET-klassbiblioteket fungerar. Om läsaren inte känner till dessa idéer kan de leta upp dem med hjälp av learn.microsoft.com eller IntelliSense.
- Kodkommentarerna ger inte någon kontext för det problem som koden löser. De här kommentarerna anses vara av låg kvalitet eftersom läsaren inte ges någon insikt i kodens syfte, särskilt hur den hänger ihop med det övergripande systemet.

Ta bort befintliga kommentarer.

Din kod bör matcha den här:

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

Observera att koden redan är mindre rörig.

Om du vill lägga till en kommentar som förklarar syftet med koden på högre nivå uppdaterar du koden på följande sätt:

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

Det är subjektivt hur användbar en kommentar anses vara. När det gäller kodens läsbarhet bör du göra det du själv anser är bäst. Gör det du anser förbättrar kodens läsbarhet på bästa sätt.

Sammanfattning

Här är de viktigaste lärdomarna från den här övningen:

Använd kodkommentarer för att beskriva det problem som koden löser så att det framgår tydligt för dig själv.
Använd inte kodkommentarer som förklarar hur C# eller .NET-klassbiblioteket fungerar.
Använd kodkommentarer när du tillfälligt provar alternativa lösningar tills du är redo att gå över till den nya kodlösningen. Därefter kan du ta bort den gamla koden.
Lita aldrig på kommentarer. De återspeglar kanske inte kodens aktuella status efter många ändringar och uppdateringar.

Feedback

Var den här sidan till hjälp?