Упражнение. Создание эффективных комментариев кода

  • 13 минут

В этом упражнении вы добавите заметки в код и временно отключите определенные строки кода из компиляции. Затем вы узнаете, как компилятор C# понимает пробелы и как использовать пробелы для повышения удобочитаемости кода.

Что такое комментарий к коду?

Комментарий к коду — это инструкция для компилятора, предписывающая пропустить все содержимое после символов комментария к коду на текущей строке.

// This is a code comment!

Вначале эта функция может показаться бесполезной, однако она может пригодиться в трех случаях:

  • Когда нужно оставить заметку о назначении фрагмента кода. Это может быть полезно для включения комментариев кода, описывающих цель или процесс мысли при написании особенно сложного набора инструкций по написанию кода. В будущем вы сами скажете себе "спасибо".
  • Если вы хотите временно удалить код из приложения, чтобы опробовать другой подход, но не уверены, что новая идея заработает. Вы можете закомментировать код, написать новый код, а после того, как вы убедитесь в работоспособности нового кода, можете безопасно удалить старый (который был закомментирован).
  • Добавление такого сообщения, как TODO, чтобы не забыть впоследствии изучить этот фрагмент кода. Хотя вы должны использовать это разумно, это полезный подход. Работая над другой функцией, вы можете заметить строку, вызывающую опасения. Вместо того чтобы игнорировать новую проблему, можно пометить ее для дальнейшего изучения.

Примечание.

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

Подготовка среды программирования

Этот модуль включает упражнения, которые помогут вам выполнить сборку и запуск примера кода. Рекомендуется выполнить эти действия с помощью Visual Studio Code в качестве среды разработки. Использование Visual Studio Code для этих действий поможет вам стать более удобным написанием и выполнением кода в среде разработчика, которая используется специалистами по всему миру.

  1. Откройте Visual Studio Code.

    Для открытия Visual Studio Code можно использовать меню Windows (или эквивалентный ресурс для другой ОС).

  2. В меню "Файл Visual Studio Code" выберите "Открыть папку".

  3. В диалоговом окне "Открыть папку " перейдите в папку "Рабочий стол Windows".

    Если у вас есть другое расположение папки, в котором хранятся проекты кода, вместо этого можно использовать это расположение папки. Для этого обучения важно иметь расположение, которое легко найти и помнить.

  4. В диалоговом окне "Открыть папку " выберите "Выбрать папку".

    Если появится диалоговое окно безопасности с запросом доверия авторам, нажмите кнопку "Да".

  5. В меню Терминала Visual Studio Code выберите Новый терминал.

    Обратите внимание, что в командной строке на панели терминала отображается путь к папке текущей папки. Рассмотрим пример.

    C:\Users\someuser\Desktop>

    Примечание.

    Если вы работаете на собственном компьютере, а не в песочнице или размещенной среде, и вы выполнили другие модули Microsoft Learn в этой серии C#, возможно, вы уже создали папку проекта для примеров кода. Если это так, можно пропустить следующий шаг, который используется для создания консольного приложения в папке TestProject.

  6. В командной строке терминала, чтобы создать консольное приложение в указанной папке, введите следующую строку:

    dotnet new console -o ./CsharpProjects/TestProject

    Эта команда .NET CLI использует шаблон программы .NET для создания проекта консольного приложения C# в указанном расположении папки. Команда создает папки CsharpProjects и TestProject для вас .csproj и использует TestProject в качестве имени файла.

    Если отображается сообщение о том, что файлы уже существуют, перейдите к следующим шагам. Вы повторно используете существующие файлы проекта.

  7. В представлении EXPLORER разверните папку CsharpProjects .

    Вы увидите папку TestProject и два файла, файл программы C# с именем Program.cs и файл проекта C# с именем TestProject.csproj.

  8. В меню "Файл Visual Studio Code" выберите "Открыть папку".

  9. В диалоговом окне "Открыть папку " выберите папку CsharpProjects и выберите "Выбрать папку".

  10. В представлении EXPLORER разверните папку TestProject и выберите Program.cs.

  11. Удалите существующие строки кода.

    Вы будете использовать этот консольный проект C# для создания, сборки и запуска примеров кода во время этого модуля.

  12. Закройте панель терминала.

Создание и использование комментариев кода

В этой задаче вы создадите и удалите различные типы комментариев кода.

  1. На панели редактора Visual Studio Code введите следующий код:

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

  2. Чтобы изменить код с комментариями и исправлениями кода, обновите код следующим образом:

    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. Просмотрите комментарии и обновления кода.

    Обратите внимание, что примечания кода используются для документирования потенциального изменения и временно отключают старое сообщение при тестировании нового сообщения. Следующий шаг — протестировать обновление. Если вы удовлетворены новым кодом, вы можете безопасно удалить старый код, который был закомментирован. Это более безопасный, более методичный подход к изменению рабочего кода, пока вы не убедитесь, что вы готовы окончательно удалить его.

  4. В меню "Файл Visual Studio Code" нажмите кнопку "Сохранить".

  5. В представлении EXPLORER откройте терминал в папке TestProject, щелкните правой кнопкой мыши TestProject и выберите "Открыть в интегрированном терминале".

  6. В командной строке терминала введите dotnet run и нажмите клавишу ввода.

    Должен появиться следующий результат:

    Bob purchased 7 widgets.

    Опять же, если вы удовлетворены обновлениями, удалите старый код, который закомментирован.

  7. Удалите комментарии кода.

    Код должен принять следующий вид:

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

  8. Чтобы применить комментарий блока, который примечает несколько строк, обновите код следующим образом:

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

    Примечания блокируются, если вам нужно написать длинный комментарий или удалить множество строк кода. Блокировать примечания используются /* в начале кода и */ в конце. Использование комментария блока — самый быстрый и простой способ отключить три или более строк кода.

  9. Замените существующий код следующим кодом:

    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#, с которыми вы можете быть не знакомы. Вам не нужно понимать, что именно делает код, чтобы оценить, как комментарии способны помочь читателям понять назначение кода.

  10. На минуту, чтобы узнать, можно ли определить назначение кода.

    Просматривая комментарии, вы можете понять, что делает код (при условии, что комментарии точно отражают текущее его состояние и обновлялись по мере изменения кода). Но можете ли вы предположить, для чего создавался этот код? Было бы не полезно, если бы в верхней части файла кода существовало некоторое объяснение, которое предоставило некоторый контекст и описало его назначение?

  11. Рассмотрим, как улучшить комментарии.

    Обратите внимание, что есть две основные проблемы с этими комментариями:

    • Комментарии к коду необязательно объясняют очевидную функциональность отдельных строк кода. Они считаются низкокачественными комментариями, так как просто объясняют принцип работы C# или методов из библиотеки классов .NET. Если читатель не знаком с этими идеями, они могут искать их с помощью learn.microsoft.com или IntelliSense.
    • Комментарии к коду не предоставляют контекст для проблемы, решаемой этим кодом. Они считаются низкокачественными комментариями, так как читатель не получает сведения о назначении кода, особенно о его связях с более крупной системой.

  12. Удалите существующие комментарии.

    Код должен принять следующий вид:

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

    Обратите внимание, что код уже менее загроможден.

  13. Чтобы добавить комментарий, объясняющий назначение кода более высокого уровня, обновите код следующим образом:

    /*
  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.
  • Используйте комментарии к коду при временной оценке альтернативных решений. Когда вы будете готовы к реализации нового решения, можете удалить старый код.
  • Никогда не доверяйте комментариям. Они могут не отражать текущее состояние кода после множества изменений и обновлений.