Ćwiczenie — tworzenie skutecznych komentarzy kodu

{liczbaMinut} minut

W tym ćwiczeniu dodasz notatki do kodu i tymczasowo wyłączysz niektóre wiersze kodu z kompilacji. Następnie dowiesz się, jak kompilator języka C# rozumie białe znaki i jak używać białych znaków w celu zwiększenia czytelności kodu.

Co to jest komentarz kodu?

Komentarz kodu to instrukcja kompilatora, która nakazuje ignorowanie całej zawartości po symbolach komentarza kodu w bieżącym wierszu.

// This is a code comment!

Na pierwszy rzut oka nie wydaje się to przydatne, jednak znajduje zastosowanie w następujących trzech sytuacjach:

Gdy chcesz pozostawić uwagę dotyczącą przeznaczenia fragmentu kodu. Przydatne może być dołączenie komentarzy do kodu opisujących cel lub proces myślowy podczas pisania szczególnie trudnego zestawu instrukcji kodowania. W przyszłości podziękujesz sobie za to.
Gdy chcesz tymczasowo usunąć kod z aplikacji, aby wypróbować inne podejście, ale nie masz jeszcze pewności, że nowy pomysł będzie działać. Możesz zmienić kod w komentarz, napisać nowy kod i, gdy będziesz mieć pewność, że nowy kod działa w pożądany sposób, bezpiecznie usunąć stary (zmieniony w komentarz) kod.
Dodanie wiadomości, takiej jak TODO, która ma przypominać o konieczności późniejszego przyglądnięcia się danemu fragmentowi kodu. Chociaż należy używać tego rozsądnie, jest to przydatne podejście. Możesz pracować z inną funkcją, gdy przeczytasz wiersz kodu, który budzi obawy. Zamiast je ignorować, możesz oznaczyć wiersz do późniejszego zbadania.

Uwaga

Komentarze kodu powinny służyć do powiedzieć, czego nie może wykonać kod. Często deweloperzy aktualizują kod, lecz zapominają o zaktualizowaniu komentarzy kodu. Najlepszym rozwiązaniem jest użycie komentarzy na potrzeby koncepcji wyższego poziomu, a nie dodawanie komentarzy dotyczących sposobu działania poszczególnych wierszy kodu.

Przygotowywanie środowiska kodowania

Ten moduł zawiera ćwiczenia, które prowadzą cię przez proces tworzenia i uruchamiania przykładowego kodu. Zachęcamy do wykonania tych działań przy użyciu programu Visual Studio Code jako środowiska programistycznego. Korzystanie z programu Visual Studio Code dla tych działań pomoże Ci lepiej pisać i uruchamiać kod w środowisku deweloperów używanym przez specjalistów na całym świecie.

Otwórz Visual Studio Code.

Aby otworzyć program Visual Studio Code, możesz użyć menu Start systemu Windows (lub równoważnego zasobu dla innego systemu operacyjnego).
W menu Plik programu Visual Studio Code wybierz pozycję Otwórz folder.
W oknie dialogowym Otwieranie folderu przejdź do folderu Pulpit systemu Windows.

Jeśli masz inną lokalizację folderu, w której są utrzymywane projekty kodu, możesz zamiast tego użyć tej lokalizacji folderu. Na potrzeby tego szkolenia ważne jest, aby mieć lokalizację, która jest łatwa do zlokalizowania i zapamiętania.
W oknie dialogowym Otwieranie folderu wybierz pozycję Wybierz folder.

Jeśli zostanie wyświetlone okno dialogowe zabezpieczeń z pytaniem, czy ufasz autorom, wybierz pozycję Tak.
W menu Terminal programu Visual Studio Code wybierz pozycję Nowy terminal.

Zwróć uwagę, że wiersz polecenia w panelu Terminal wyświetla ścieżkę folderu dla bieżącego folderu. Na przykład:
```
C:\Users\someuser\Desktop>
```
Uwaga

Jeśli pracujesz na własnym komputerze, a nie w piaskownicy lub w środowisku hostowanym i ukończono inne moduły Microsoft Learn w tej serii języka C#, być może utworzono już folder projektu dla przykładów kodu. Jeśli tak jest, możesz pominąć następny krok, który służy do tworzenia aplikacji konsolowej w folderze TestProject.
W wierszu polecenia terminalu, aby utworzyć nową aplikację konsolową w określonym folderze, wprowadź następujący monit:
```
dotnet new console -o ./CsharpProjects/TestProject
```
To polecenie interfejsu wiersza polecenia platformy .NET używa szablonu programu .NET do utworzenia nowego projektu aplikacji konsolowej języka C# w określonej lokalizacji folderu. Polecenie tworzy foldery CsharpProjects i TestProject i używa elementu TestProject jako nazwy .csproj pliku.

Jeśli zostanie wyświetlony komunikat informujący o tym, że pliki już istnieją, przejdź do następnych kroków. Użyjesz ponownie istniejących plików projektu.
W widoku EKSPLORATOR rozwiń folder CsharpProjects .

Powinien zostać wyświetlony folder TestProject i dwa pliki, plik programu C# o nazwie Program.cs i plik projektu C# o nazwie TestProject.csproj.
W menu Plik programu Visual Studio Code wybierz pozycję Otwórz folder.
W oknie dialogowym Otwieranie folderu wybierz folder CsharpProjects , a następnie wybierz pozycję Wybierz folder.
W widoku EKSPLORATOR rozwiń folder TestProject, a następnie wybierz pozycję Program.cs.
Usuń istniejące wiersze kodu.

Ten projekt konsoli języka C# będzie używany do tworzenia, kompilowania i uruchamiania przykładów kodu w tym module.
Zamknij panel Terminal.

Tworzenie i używanie komentarzy kodu

W tym zadaniu utworzysz i usuniesz różne typy komentarzy kodu.

W panelu Edytora programu Visual Studio Code wprowadź następujący kod:

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

Aby zmodyfikować kod za pomocą komentarzy i poprawek kodu, zaktualizuj kod w następujący sposób:

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

Pośmiń chwilę na przejrzenie komentarzy i aktualizacji kodu.

Zwróć uwagę, że komentarze kodu są używane do dokumentowania potencjalnej zmiany i tymczasowego wyłączenia starego komunikatu podczas testowania nowej wiadomości. Następnym krokiem będzie przetestowanie aktualizacji. Jeśli nowy kod jest zadowalający, możesz bezpiecznie usunąć stary kod, który został skomentowany. Jest to bezpieczniejsze, bardziej metodyczne podejście do modyfikowania kodu roboczego, dopóki nie masz pewności, że wszystko będzie gotowe do jego trwałego usunięcia.
W menu Plik programu Visual Studio Code kliknij przycisk Zapisz.
W widoku EKSPLORATOR, aby otworzyć terminal w lokalizacji folderu TestProject, kliknij prawym przyciskiem myszy pozycję TestProject, a następnie wybierz polecenie Otwórz w zintegrowanym terminalu.
W wierszu polecenia terminalu wpisz polecenie dotnet run , a następnie naciśnij Enter.

Powinny zostać wyświetlone następujące dane wyjściowe:
```
Bob purchased 7 widgets.
```
Ponownie, jeśli aktualizacje są zadowalające, usuń stary kod, który został skomentowany.

Usuń komentarze kodu.

Kod powinien być zgodny z następującym:

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

Aby zastosować komentarz bloku, który komentarze zawiera wiele wierszy, zaktualizuj kod w następujący sposób:
```
/*
string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
*/
```
Komentarze blokowe są doskonałe, jeśli musisz napisać długi komentarz lub usunąć wiele wierszy kodu. Blokuj komentarze używają obiektu /* na początku kodu i */ na końcu. Użycie komentarza blokowego jest najszybszym i najprostszym sposobem wyłączenia trzech lub większej liczby wierszy kodu.

Zastąp istniejący kod następującym kodem:

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

Uwaga

Ten kod zawiera wiele koncepcji języka C#, które mogą być dla Ciebie nowe. Nie trzeba rozumieć, co robi kod, aby docenić, jak komentarze mogą pomóc czytelnikom zrozumieć przeznaczenie kodu.

Pośmiń minutę, aby sprawdzić, czy możesz ustalić przeznaczenie kodu.

Patrząc na komentarze, możesz być w stanie określić, co robi kod (przy założeniu, że komentarze dokładnie opisują bieżący stan i były aktualizowane w miarę aktualizowania kodu). Ale czy potrafisz odgadnąć, dlaczego ten kod istnieje? Czy nie byłoby przydatne, gdyby w górnej części pliku kodu istniało wyjaśnienie, które dostarczyło jakiś kontekst i opisało jego przeznaczenie?
Zastanów się, jak poprawić komentarze.

Zwróć uwagę, że istnieją dwa główne problemy z tymi komentarzami:
- Komentarze kodu niepotrzebnie objaśniają oczywiste funkcjonalności poszczególnych wierszy kodu. Takie komentarze są uznawane za komentarze niskiej jakości, ponieważ tylko wyjaśniają sposób działania języka C# lub metod biblioteki klas platformy .NET. Jeśli czytelnik nie jest w stanie zapoznać się z tymi pomysłami, może wyszukać je przy użyciu learn.microsoft.com lub intelliSense.
- Komentarze kodu nie określają żadnego kontekstu dla problemu rozwiązywanego przez kod. Są one uznawane za komentarze niskiej jakości, ponieważ czytnik nie uzyskuje żadnego wglądu w przeznaczenie kodu, a szczególnie w jego powiązanie z większym systemem.

Usuń istniejące komentarze.

Kod powinien być zgodny z następującym:

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

Zwróć uwagę, że kod jest już mniej zaśmiecony.

Aby dodać komentarz wyjaśniający cel wyższego poziomu kodu, zaktualizuj kod w następujący sposób:

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

Przydatność komentarza to rzecz subiektywna. We wszystkich kwestiach dotyczących czytelności kodu należy używać własnego osądu. Postępuj w sposób, który według Ciebie najlepiej zwiększy przejrzystość kodu.

Podsumowanie

Najważniejsze wnioski z tego ćwiczenia:

Używaj komentarzy kodu, aby pozostawić sobie niosące treść komentarze dotyczące problemu rozwiązywanego przez kod.
Nie używaj komentarzy kodu, które wyjaśniają sposób działania języka C# lub biblioteki klas platformy .NET.
Używaj komentarzy kodu podczas tymczasowego wypróbowywania alternatywnych rozwiązań do momentu, gdy wszystko będzie gotowe do zatwierdzenia nowego kodu rozwiązania — wtedy też możesz usunąć stary kod.
Nigdy nie ufaj komentarzom. Mogą one nie odzwierciedlać bieżącego stanu kodu po wielu zmianach i aktualizacjach.

Opinia

Czy ta strona była pomocna?