Oefening: effectieve codeopmerkingen maken

  • 13 minuten

In deze oefening voegt u notities toe aan uw code en schakelt u bepaalde regels code tijdelijk uit van compilatie. Vervolgens bekijkt u hoe de C#-compiler witruimte begrijpt en hoe u witruimte gebruikt om de leesbaarheid van uw code te vergroten.

Wat is commentaar bij code?

Commentaar bij een code is een instructie voor de compiler om alles wat er na de commentaarsymbolen in de huidige regel komt te negeren.

// This is a code comment!

Dit lijkt misschien niet nuttig, maar dat is het wel in deze drie situaties:

  • Wanneer u een opmerking wilt plaatsen over de intentie van een codefragment. Het kan handig zijn om codeopmerkingen op te nemen die het doel of het gedachteproces beschrijven wanneer u een bijzonder uitdagende set code-instructies schrijft. Daar zult u later veel aan hebben.
  • Wanneer u tijdelijk code uit uw toepassing wilt verwijderen om een andere aanpak te proberen, maar u nog niet zeker weet of uw nieuwe idee wel werkt. U kunt commentaar maken van de code en de nieuwe code schrijven. Zodra u zeker weet dat de nieuwe code naar wens werkt, kunt u de oude code (waarvan u commentaar hebt gemaakt) veilig verwijderen.
  • Wanneer u een bericht als TODO toevoegt om u eraan te herinneren dat u later nog eens naar een bepaald codefragment moet kijken. Hoewel u dit verstandig moet gebruiken, is het een handige benadering. Misschien werkt u aan een andere functie wanneer u een coderegel leest die u zorgen baart. In plaats van dit nieuwe aandachtspunt te negeren, kunt u het markeren om later te onderzoeken.

Notitie

Codeopmerkingen moeten worden gebruikt om te zeggen wat de code niet kan. Vaak werken ontwikkelaars hun code bij, maar vergeten ze het commentaar bij de code bij te werken. Het is het beste om commentaar te gebruiken voor ideeën op een hoger niveau en geen commentaar toe te voegen over de werking van individuele coderegels.

Uw coderingsomgeving voorbereiden

Deze module bevat oefeningen die u begeleiden bij het bouwen en uitvoeren van voorbeeldcode. U wordt aangeraden deze activiteiten uit te voeren met Behulp van Visual Studio Code als uw ontwikkelomgeving. Het gebruik van Visual Studio Code voor deze activiteiten helpt u om comfortabeler code te schrijven en uit te voeren in een ontwikkelomgeving die wordt gebruikt door professionals wereldwijd.

  1. Open Visual Studio Code.

    U kunt de Windows-Startmenu (of een equivalente resource voor een ander besturingssysteem) gebruiken om Visual Studio Code te openen.

  2. Selecteer Map openen in het menu Visual Studio Code-bestand.

  3. Navigeer in het dialoogvenster Map openen naar de map Windows-bureaublad.

    Als u een andere maplocatie hebt waar u codeprojecten bewaart, kunt u die maplocatie gebruiken. Voor deze training is het belangrijk om een locatie te hebben die gemakkelijk te vinden en te onthouden is.

  4. Selecteer Map selecteren in het dialoogvenster Map openen.

    Als u een beveiligingsdialoogvenster ziet waarin u wordt gevraagd of u de auteurs vertrouwt, selecteert u Ja.

  5. Selecteer In het menu Visual Studio Code Terminal de optie Nieuwe terminal.

    U ziet dat in een opdrachtprompt in het terminalvenster het mappad voor de huidige map wordt weergegeven. Bijvoorbeeld:

    C:\Users\someuser\Desktop>

    Notitie

    Als u op uw eigen pc werkt in plaats van in een sandbox of gehoste omgeving en u andere Microsoft Learn-modules in deze C#-serie hebt voltooid, hebt u mogelijk al een projectmap gemaakt voor codevoorbeelden. Als dat het geval is, kunt u de volgende stap overslaan, die wordt gebruikt om een console-app te maken in de map TestProject.

  6. Voer bij de terminalopdrachtprompt de volgende prompt in om een nieuwe consoletoepassing in een opgegeven map te maken:

    dotnet new console -o ./CsharpProjects/TestProject

    Deze .NET CLI-opdracht maakt gebruik van een .NET-programmasjabloon om een nieuw C#-consoletoepassingsproject te maken op de opgegeven maplocatie. Met de opdracht worden de mappen CsharpProjects en TestProject voor u gemaakt en wordt TestProject gebruikt als de naam van uw .csproj bestand.

    Als er een bericht wordt weergegeven waarin wordt aangegeven dat de bestanden al bestaan, gaat u verder met de volgende stappen. U gebruikt de bestaande projectbestanden opnieuw.

  7. Vouw in de EXPLORER-weergave de map CsharpProjects uit .

    U ziet de map TestProject en twee bestanden, een C#-programmabestand met de naam Program.cs en een C#-projectbestand met de naam TestProject.csproj.

  8. Selecteer Map openen in het menu Visual Studio Code-bestand.

  9. Selecteer in het dialoogvenster Map openen de map CsharpProjects en klik vervolgens op Map selecteren.

  10. Vouw in de explorer-weergave de map TestProject uit en selecteer Program.cs.

  11. Verwijder de bestaande coderegels.

    U gebruikt dit C#-consoleproject om codevoorbeelden te maken, te bouwen en uit te voeren tijdens deze module.

  12. Sluit het deelvenster Terminal.

Codeopmerkingen maken en gebruiken

In deze taak maakt en verwijdert u verschillende typen codeopmerkingen.

  1. Voer in het deelvenster Visual Studio Code Editor de volgende code in:

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

  2. Als u uw code wilt wijzigen met opmerkingen en revisies van code, werkt u uw code als volgt bij:

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

  3. Neem even de tijd om uw opmerkingen en code-updates te bekijken.

    U ziet dat de codeopmerkingen worden gebruikt om de mogelijke wijziging te documenteren en om het oude bericht tijdelijk uit te schakelen terwijl u het nieuwe bericht test. De volgende stap bestaat uit het testen van uw update. Als u tevreden bent met de nieuwe code, kunt u de oude code die als commentaar is gemarkeerd, veilig verwijderen. Dit is een veiligere, methodischere benadering voor het wijzigen van werkcode totdat u ervan overtuigd bent dat u er klaar voor bent om deze definitief te verwijderen.

  4. Klik in het menu Visual Studio Code File op Opslaan.

  5. Als u in de EXPLORER-weergave een Terminal wilt openen op de locatie van de map TestProject, klikt u met de rechtermuisknop op TestProject en selecteert u Openen in geïntegreerde terminal.

  6. Typ dotnet run bij de Terminal-opdrachtprompt en druk op Enter.

    U moet de volgende uitvoer zien:

    Bob purchased 7 widgets.

    Als u tevreden bent met uw updates, verwijdert u de oude code die als commentaar is toegevoegd.

  7. Verwijder de codeopmerkingen.

    Uw code moet er zo uitzien:

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

  8. Als u een blokopmerking wilt toepassen die meerdere regels als commentaar bevat, werkt u de code als volgt bij:

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

    Blokopmerkingen zijn handig als u een lange opmerking moet schrijven of veel regels code moet verwijderen. Blokopmerkingen gebruiken een /* aan het begin van de code en een */ aan het einde. Het gebruik van een blokcommentaar is de snelste en eenvoudigste manier om drie of meer regels code uit te schakelen.

  9. Vervang uw bestaande code door het volgende:

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

    Notitie

    Er zijn veel C#-concepten in deze codevermelding die nieuw voor u kunnen zijn. Het is niet nodig om te begrijpen wat de code doet om in te zien hoe nuttig commentaar kan zijn om lezers te helpen om het doel van de code te doorgronden.

  10. Neem even de tijd om te zien of u het doel van de code kunt achterhalen.

    Op basis van het commentaar kunt u achterhalen wat de code doet (ervan uitgaand dat het commentaar een nauwkeurige beschrijving is van de huidige status en dat het is bijgewerkt als de code werd bijgewerkt). Maar kunt u raden wat de functie van deze code is? Zou het niet nuttig zijn als er boven aan het codebestand wat uitleg was die enige context bood en het doel ervan heeft beschreven?

  11. Bedenk hoe u de opmerkingen zou verbeteren.

    U ziet dat er twee belangrijke problemen zijn met deze opmerkingen:

    • Het commentaar bestaat uit overbodige uitleg over de heldere functionaliteit van afzonderlijke coderegels. Dit wordt beschouwd als commentaar van lage kwaliteit, omdat het alleen aangeeft hoe C# of methoden van de .NET Framework-klassebibliotheek werken. Als de lezer niet bekend is met deze ideeën, kunnen ze ze opzoeken met behulp van learn.microsoft.com of IntelliSense.
    • Het commentaar biedt geen context voor het probleem dat door de code wordt opgelost. Dit wordt beschouwd als commentaar van lage kwaliteit omdat de lezer geen inzicht krijgt in het doel van deze code, vooral als het een groot systeem betreft.

  12. Verwijder de bestaande opmerkingen.

    Uw code moet er zo uitzien:

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

    U ziet dat de code al minder rommelig is.

  13. Als u een opmerking wilt toevoegen waarmee het hogere doel van uw code wordt uitgelegd, werkt u uw code als volgt bij:

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

    De bruikbaarheid van commentaar is subjectief. Ga bij alle zaken met betrekking tot de leesbaarheid van code op uw eigen oordeel af. Doe wat u denkt dat het beste is om de helderheid van uw code te verbeteren.

Samenvatting

De belangrijkste opgedane kennis in deze oefening:

  • Gebruik commentaar bij code om zinvolle opmerkingen voor uzelf achter te laten over het probleem dat met uw code wordt opgelost.
  • Gebruik geen commentaar waarin wordt uitgelegd hoe C# of de .NET Framework-klassebibliotheek werkt.
  • Gebruik commentaar bij code wanneer u tijdelijk alternatieve oplossingen uitprobeert. Als u eraan toe bent om de nieuwe codeoplossing door te voeren, kunt u de oude code verwijderen.
  • Vertrouw nooit op commentaar. Deze kan achterlopen op de code als deze vaak is gewijzigd.