Вправа – створення ефективних коментарів до коду

13 хвилин

У цій вправі ви додасте нотатки до коду та тимчасово вимкнете певні рядки коду від компіляції. Потім ви дізнаєтеся, як компілятор C# розуміє пробіли та як використовувати пробіли для підвищення зручності читання коду.

Що таке коментар до коду?

Примітка до коду – це інструкція компілятору ігнорувати всі елементи після символів примітки коду в поточному рядку.

// This is a code comment!

Спочатку це може здатися не корисним, однак воно корисне в трьох ситуаціях:

Якщо ви хочете залишити нотатку про намір проходження коду. Якщо ви пишете особливо складний набір інструкцій із кодування, можна додати примітки до коду, які описують мету або процес думок. Ваше майбутнє себе буде дякувати вам.
Якщо потрібно тимчасово видалити код із програми, щоб спробувати інший підхід, але ви ще не впевнені, що нова ідея спрацює. Ви можете прокоментувати код, написати новий код, і після того, як ви переконаєтеся, що новий код працюватиме належним чином, ви можете безпечно видалити старий (примітний код).
Додавання повідомлення нагадає TODO вам про певний уривок коду пізніше. Хоча ви повинні використовувати це розсудливо, це корисний підхід. Ви можете працювати над іншою функцією, коли читаєте рядок коду, який викликає занепокоєння. Замість того, щоб ігнорувати нове занепокоєння, ви можете позначити його для розслідування пізніше.

Примітка

Примітки коду слід використовувати, щоб сказати, що код не може. Часто розробники оновлюють свій код, але забувають оновити примітки до коду. Радимо використовувати примітки для ідей вищого рівня, а не додавати примітки про те, як працює окремий рядок коду.

Підготовка середовища кодування

Цей модуль містить вправи, які допоможуть вам побудувати та запустити зразок коду. Вам рекомендується виконати ці дії, використовуючи Visual Studio Code як середовище розробки. Використання коду Visual Studio для цих дій допоможе вам стати більш зручним написанням і виконанням коду в середовищі розробників, яке використовують професіонали по всьому світу.

Відкрийте Код Visual Studio.

Щоб відкрити код Visual Studio, можна скористатися меню "Пуск" Windows (або еквівалентним ресурсом для іншої ОС).
У меню Код Visual Studio Файл виберіть Відкрити папку.
У діалоговому вікні Відкрити папку перейдіть до папки "Робочий стіл Windows".

Якщо у вас є інше розташування папки, де зберігаються проекти коду, натомість можна використовувати це розташування папки. Для цього навчання важливо мати розташування, яке легко знайти та запам'ятати.
У діалоговому вікні Відкрити папку виберіть Вибрати папку.

Якщо з'явиться діалогове вікно безпеки з запитанням, чи довіряєте ви авторам, виберіть Так.
У меню коду Visual Studio Code виберіть Новий термінал.

Зверніть увагу, що в командному рядку на панелі терміналів відображається шлях до папки для поточної папки. Наприклад:
```
C:\Users\someuser\Desktop>
```
Примітка

Якщо ви працюєте на власному ПК, а не в ізольованому середовищі або в розміщеному середовищі, а завершили інші модулі Microsoft Learn у цій серії C# , можливо, ви вже створили папку проекту для зразків коду. У такому разі можна пропустити наступний крок, який використовується для створення консолі в папці TestProject.
У командному рядку термінала, щоб створити нову програму консолі в указаній папці, введіть такий запит:
```
dotnet new console -o ./CsharpProjects/TestProject
```
Ця команда .NET CLI використовує шаблон програми .NET для створення нового проекту програми консолі C# у вказаному розташуванні папки. Ця команда створює папки CsharpProjects і TestProject і використовує TestProject як ім'я .csproj файлу.

Якщо відображається повідомлення про те, що файли вже існують, виконайте наступні кроки. Ви повторно використовуватимете наявні файли проекту.
У поданні EXPLORER розгорніть папку CsharpProjects .

Має відобразитися папка TestProject і два файли, файл програми C# з іменем Program.cs і файл проекту C# з іменем TestProject.csproj.
У меню Код Visual Studio Файл виберіть Відкрити папку.
У діалоговому вікні Відкрити папку виберіть папку CsharpProjects , а потім натисніть кнопку Вибрати папку.
У поданні EXPLORER розгорніть папку TestProject і виберіть Program.cs.
Видалення наявних рядків коду.

Ви використовуватимете цей проект консолі C# для створення, створення та виконання зразків коду під час цього модуля.
Закрийте панель терміналів.

Створення та використання приміток коду

У цьому завданні буде створено та видалено різні типи кодових приміток.

На панелі редактора коду Visual Studio введіть такий код:

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

Щоб змінити код із примітками та виправленнями коду, оновіть код, як це зробити:

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

Ознайомтеся з примітками та оновленнями коду за хвилину.

Зверніть увагу, що примітки коду використовуються для документування можливих змін, які вносяться, і тимчасового вимкнення старого повідомлення під час перевірки нового повідомлення. Наступним кроком буде перевірка оновлення. Якщо ви задоволені новим кодом, ви можете безпечно видалити старий код, який було прокоментовано. Це безпечніший і більш методичний підхід до змінення робочого коду, доки ви не переконаєтеся, що готові остаточно видалити його.
У меню Файл коду Visual Studio натисніть кнопку Зберегти.
У поданні EXPLORER, щоб відкрити термінал у розташуванні папки TestProject, клацніть правою кнопкою миші елемент TestProject, а потім виберіть відкрити в інтегрованому терміналі.
У командному рядку термінала введіть dotnet run і натисніть клавішу Enter.

Ви побачите такий результат:
```
Bob purchased 7 widgets.
```
Знову ж таки, якщо ви задоволені оновленнями, видаліть старий код, прокоментований.

Видаліть примітки коду.

Код має відповідати таким:

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

Щоб застосувати заблоковану примітку, яка виділяє кілька рядків, оновіть код таким чином:
```
/*
string firstName = "Bob";
int widgetsPurchased = 7;
Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
*/
```
Блокування приміток чудово підходить, якщо потрібно написати довгу примітку або видалити багато рядків коду. У параметрах блокування приміток використовується /* на початку коду та */ в кінці. Використання блок-примітки – це найшвидший і найпростіший спосіб вимкнути три або більше рядків коду.

Замініть наявний код на такий:

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

Примітка

У цьому коді є багато понять C#, які можуть бути новими для вас. Не обов'язково розуміти, що робить код, щоб оцінити, як коментарі можуть допомогти читачам зрозуміти призначення коду.

Зачекайте хвилинку, щоб дізнатися, чи можна визначити призначення коду.

З огляду на примітки, ви можете з'ясувати, що робить код (якщо примітки точно описують поточний стан і оновлюються під час оновлення коду). Але чи можете ви здогадатися, чому цей код існує? Чи не було б корисно, якби у верхній частині файлу коду з'явилися пояснення, які надали певний контекст і описали його призначення?
Поміркуйте над тим, як покращити примітки.

Зверніть увагу, що є дві основні проблеми з такими примітками:
- У коментарях коду зайве пояснюється очевидна функціональність окремих рядків коду. Вони вважаються неякісними примітками, оскільки вони просто пояснюють, як працюють C# або методи бібліотеки класу .NET. Якщо читач не знайомий з цими ідеями, вони можуть шукати їх за допомогою learn.microsoft.com або IntelliSense.
- У коментарях коду немає контексту для вирішення проблеми за допомогою коду. Вони вважаються неякісними примітками, оскільки читач не може зрозуміти призначення цього коду, тим більше, що він відноситься до більшої системи.

Видалення наявних приміток.

Код має відповідати таким:

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

Зверніть увагу, що код уже менш захаращений.

Щоб додати примітку, яка пояснює призначення коду вищого рівня, оновіть код таким чином:

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

Корисність примітки суб'єктивна. У всіх питаннях, пов'язаних із читабельністю коду, ви повинні використовувати своє найкраще судження. Робіть те, що, на вашу думку, найкраще, щоб покращити ясність коду.

Повторити введення

Основні виноси з цієї вправи:

Використовуйте примітки коду, щоб залишити змістовні нотатки собі про проблему, що вирішує ваш код.
Не використовуйте примітки коду, які пояснюють, як працює C# або .NET Class Library.
Використовуйте примітки коду під час тимчасової спроби альтернативних рішень, доки не будете готові взяти на себе зобов'язання щодо нового коду, у який момент можна видалити старий код.
Ніколи не довіряйте коментарям. Вони можуть не відображати поточний стан коду після багатьох змін і оновлень.

Зворотний зв’язок

Чи була ця сторінка корисна?