Übung: Erstellen effektiver Codekommentare

  • 13 Minuten

In dieser Übung fügen Sie Ihrem Code Anmerkungen hinzu und deaktivieren vorübergehend die Kompilierung bestimmter Codezeilen. Anschließend wird erläutert, wie der C#-Compiler den Leerraum interpretiert und wie Leerraum dazu verwendet werden kann, die Lesbarkeit von Code zu verbessern.

Was ist ein Codekommentar?

Ein Codekommentar ist eine Anweisung an den Compiler, in der aktuellen Zeile alle Zeichen zu ignorieren, die auf die Codekommentarsymbole folgen.

// This is a code comment!

Auf den ersten Blick mag dies unnütz erscheinen, ist aber in drei Situationen nützlich:

  • Sie möchten einen Hinweis über den Zweck eines Codeausschnitts geben. Es kann hilfreich sein, Codekommentare einzufügen, um den Zweck oder Denkprozess zu beschreiben, wenn Sie besonders anspruchsvolle Codierungsanweisungen schreiben. Sie werden es sich selbst in der Zukunft danken.
  • Sie möchten Code temporär aus Ihrer Anwendung entfernen, um einen anderen Ansatz zu testen, sind aber noch nicht überzeugt, dass Ihre neue Idee erfolgreich funktioniert. Sie können den Code auskommentieren und den neuen Code schreiben, und sobald Sie davon überzeugt sind, dass der neue Code in der von Ihnen gewünschten Weise funktioniert, können Sie den alten (kommentierten) Code sicher löschen.
  • Sie fügen einen Hinweis wie TODO hinzu, um sich selbst zu erinnern, dass Sie einen bestimmten Codeausschnitt später genauer untersuchen sollten. Zwar sollten Sie diese Vorgehensweise mit Bedacht nutzen, sie stellt aber einen vernünftigen Ansatz dar. Möglicherweise arbeiten Sie an einer anderen Funktionalität, wenn Sie eine Codezeile lesen, die ein Problem verursacht. Anstatt das neue Problem zu ignorieren, markieren Sie es zur späteren Untersuchung.

Hinweis

In Codekommentaren sollte auch angegeben werden, was der Code nicht kann. Häufig aktualisieren Entwickler den Code, vergessen aber, die Codekommentare ebenfalls zu aktualisieren. Es empfiehlt sich, für allgemeine Ideen Kommentare zu verwenden, aber keine Kommentare zur Funktionsweise einer einzelnen Codezeile hinzuzufügen.

Vorbereiten Ihrer Programmierumgebung

Dieses Modul enthält Übungen zum Erstellen und Ausführen von Beispielcode. Es wird empfohlen, diese Aktivitäten mit Visual Studio Code als Entwicklungsumgebung durchzuführen. Die Verwendung von Visual Studio Code für diese Aktivitäten vereinfacht das Schreiben und Ausführen von Code in einer Entwicklerumgebung, die von Expert*innen weltweit verwendet wird.

  1. Öffnen Sie Visual Studio Code.

    Sie können das Windows-Startmenü (oder eine entsprechende Ressource für ein anderes Betriebssystem) verwenden, um Visual Studio Code zu öffnen.

  2. Klicken Sie im Visual Studio Code-Menü Datei auf Ordner öffnen.

  3. Navigieren Sie im Dialogfeld Ordner öffnen zum Windows-Ordner „Desktop“.

    Wenn Sie Codeprojekte in der Regel in einem anderen Ordner speichern, können Sie stattdessen auch diesen verwenden. Für dieses Training ist es wichtig, einen Ort zu haben, den Sie leicht finden und sich gut merken können.

  4. Klicken Sie im Dialogfeld Ordner öffnen auf Ordner auswählen.

    Wenn ein Sicherheitsdialogfeld angezeigt wird, in dem Sie gefragt werden, ob Sie den Autor*innen vertrauen, wählen Sie Ja aus.

  5. Klicken Sie im Visual Studio Code-Menü Terminal die Option Neues Terminal aus.

    Beachten Sie, dass eine Eingabeaufforderung im Panel „Terminal“ den Ordnerpfad für den aktuellen Ordner anzeigt. Beispiel:

    C:\Users\someuser\Desktop>

    Hinweis

    Wenn Sie auf Ihrem eigenen PC und nicht in einer Sandbox oder gehosteten Umgebung arbeiten und andere Microsoft Learn-Module in dieser C#-Reihe abgeschlossen haben, haben Sie möglicherweise bereits einen Projektordner für Codebeispiele erstellt. In diesem Fall können Sie den nächsten Schritt überspringen, der zum Erstellen einer Konsolen-App im Ordner „TestProject“ verwendet wird.

  6. Geben Sie an der Terminal-Eingabeaufforderung zum Erstellen einer neuen Konsolenanwendung in einem angegebenen Ordner die folgende Eingabeaufforderung ein:

    dotnet new console -o ./CsharpProjects/TestProject

    Dieser .NET-CLI-Befehl verwendet eine .NET-Programmvorlage, um ein neues C#-Konsolenanwendungsprojekt am angegebenen Ordnerspeicherort zu erstellen. Der Befehl erstellt die Ordner „CsharpProjects“ und „TestProject“ für Sie und verwendet „TestProject“ als Namen für Ihre .csproj-Datei.

    Wenn eine Meldung angezeigt wird, die Besagt, dass die Dateien bereits vorhanden sind, fahren Sie mit den nächsten Schritten fort. Sie werden die vorhandenen Projektdateien wiederverwenden.

  7. Erweitern Sie in der EXPLORER-Ansicht den Ordner "CsharpProjects ".

    Sie sollten den Ordner "TestProject " und zwei Dateien sehen, eine C#-Programmdatei mit dem Namen Program.cs und eine C#-Projektdatei namens TestProject.csproj.

  8. Klicken Sie im Visual Studio Code-Menü Datei auf Ordner öffnen.

  9. Wählen Sie im Dialogfeld "Ordner öffnen " den Ordner "CsharpProjects " und dann " Ordner auswählen" aus.

  10. Erweitern Sie in der EXPLORER-Ansicht den Ordner "TestProject", und wählen Sie dann Program.cs aus.

  11. Löschen Sie die vorhandenen Codezeilen.

    Sie verwenden dieses C#-Konsolenprojekt zum Erstellen und Ausführen von Codebeispielen im Rahmen dieses Moduls.

  12. Schließen Sie das Panel „Terminal“.

Erstellen und Verwenden von Codekommentaren

In dieser Aufgabe erstellen und entfernen Sie verschiedene Arten von Codekommentaren.

  1. Geben Sie den folgenden Code im Editor-Bereich von Visual Studio Code ein:

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

  2. Um Ihren Code um Codekommentare und -überarbeitungen zu ergänzen, aktualisieren Sie ihn wie folgt:

    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. Nehmen Sie sich etwas Zeit, um Ihre Kommentare und Codeänderungen zu überprüfen.

    Beachten Sie, dass die Codekommentare verwendet wurden, um die möglicherweise vorzunehmende Änderung zu dokumentieren und die alte Meldung vorübergehend zu deaktivieren, während die neue Meldung getestet wird. Im nächsten Schritt testen Sie Ihre Änderungen. Wenn der neue Code Ihren Vorstellungen entspricht, können Sie den alten Code, der auskommentiert wurde, sicher löschen. Dies ist ein sicherer, eher methodischer Ansatz zum Ändern von funktionierendem Code, bis eindeutig klar ist, dass der alte Code entfernt werden kann.

  4. Wählen Sie im Visual Studio Code-Menü Datei die Option Speichern aus.

  5. Klicken Sie in der EXPLORER-Ansicht auf "TestProject", um ein Terminal am Speicherort des TestProject-Ordners zu öffnen, klicken Sie mit der rechten Maustaste auf "TestProject", und wählen Sie dann " In integriertem Terminal öffnen" aus.

  6. Geben Sie in der Eingabeaufforderung des Terminals dotnet run ein, und drücken Sie dann die EINGABETASTE.

    Die folgende Ausgabe wird angezeigt.

    Bob purchased 7 widgets.

    Wenn Sie mit Ihren Änderungen zufrieden sind, löschen Sie den alten Code, der auskommentiert wurde.

  7. Löschen Sie die Codekommentare.

    Ihr Code sollte nun mit dem folgenden Codebeispiel übereinstimmen:

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

  8. Um einen Blockkommentar einzufügen, der mehrere Zeilen umfasst, aktualisieren Sie den Code wie folgt:

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

    Blockkommentare eignet sich hervorragend, wenn Sie einen langen Kommentar schreiben oder viele Codezeilen entfernen müssen. Bei Blockkommentaren steht am Anfang des Codes /* und am Ende */. Ein Blockkommentar stellt die schnellste und einfachste Möglichkeit dar, drei oder mehr Codezeilen zu deaktivieren.

  9. Ersetzen Sie den vorhandenen Code durch folgenden Code:

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

    Hinweis

    Es gibt viele C#-Konzepte in dieser Codeauflistung, die möglicherweise neu für Sie sind. Sie müssen nicht notwendigerweise begreifen, wozu dieser Code verwendet wird, um trotzdem zu erkennen, wie Kommentare den Leser in die Lage versetzen können, den Zweck des Codes zu verstehen.

  10. Nehmen Sie sich etwas Zeit, um den Zweck des Codes herauszufinden.

    Anhand der Kommentare können Sie vielleicht herausfinden, was der Code tut (vorausgesetzt, die Kommentare beschreiben genau den aktuellen Zustand und wurden aktualisiert, als der Code aktualisiert wurde). Aber können Sie erraten, warum es diesen Code gibt? Wäre es nicht hilfreich, wenn oben in der Codedatei eine Erklärung wäre, die einen Kontext bereitstellt und den Zweck beschreibt?

  11. Überlegen Sie, wie Sie die Kommentare verbessern würden.

    Beachten Sie, dass es bei diesen Kommentaren zwei grundlegende Probleme gibt:

    • In den Codekommentaren wird unnötigerweise die offensichtliche Funktionalität einzelner Codezeilen erläutert. Diese Kommentare gelten als minderwertige Kommentare, da in ihnen lediglich erläutert wird, wie C# oder Methoden der .NET-Klassenbibliothek funktionieren. Wenn Leser*innen nicht mit diesen Ideen vertraut sind, können sie unter docs.Microsoft.com oder mit IntelliSense weitere Informationen erhalten.
    • Die Codekommentare bieten keinen Kontext für das Problem, das durch den Code gelöst wird. Diese Kommentare gelten als minderwertige Kommentare, da der Leser keinen Einblick in den Zweck dieses Codes erhält, was insbesondere in Bezug auf das größere System gilt.

  12. Entfernen Sie die vorhandenen Kommentare.

    Ihr Code sollte nun mit dem folgenden Codebeispiel übereinstimmen:

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

    Beachten Sie, dass der Code bereits etwas übersichtlicher ist.

  13. Um einen Kommentar hinzuzufügen, der den allgemeinen Zweck Ihres Codes erläutert, aktualisieren Sie diesen wie folgt:

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

    Die Zweckmäßigkeit eines Kommentars ist subjektiv. In allen Aspekten bezüglich der Lesbarkeit des Codes sollten Sie sich auf Ihr Urteilsvermögen verlassen. Schreiben Sie die Kommentare, die Ihrer Meinung nach am besten geeignet sind, die Klarheit Ihres Codes zu verbessern.

Zusammenfassung

Die wichtigsten Ergebnisse dieser Übung sind folgende:

  • Verwenden Sie Codekommentare, um für sich selbst nützliche Hinweise zu dem Problem zu geben, das mit Ihrem Code gelöst wird.
  • Verwenden Sie keine Codekommentare, in denen erläutert wird, wie C# oder die .NET-Klassenbibliothek funktioniert.
  • Verwenden Sie, wenn Sie temporär alternative Lösungen testen möchten, solange Codekommentare, bis die neue Codelösung bestätigt ist. An diesem Punkt können Sie dann den alten Code löschen.
  • Vertrauen Sie Kommentaren niemals. Möglicherweise entsprechen sie nach vielen Änderungen und Aktualisierungen nicht mehr dem aktuellen Zustand des Codes.