연습 - 효과적인 코드 주석 만들기

  • 13분

이 연습에서는 코드에 메모를 추가하고 컴파일 시 특정 코드 줄을 일시적으로 사용하지 않도록 설정합니다. 그런 다음 C# 컴파일러가 공백을 이해하는 방식과 공백을 사용하여 코드 가독성을 높이는 방법을 살펴보겠습니다.

코드 주석이란?

코드 주석은 컴파일러에 현재 줄의 코드 주석 기호 뒤에 나오는 모든 항목을 무시하도록 하는 명령입니다.

// This is a code comment!

처음에는 유용하지 않을 수 있지만 다음과 같은 세 가지 상황에서는 유용합니다.

  • 코드 경로 의도에 대한 메모를 남기려고 합니다. 이는 특히 까다로운 코딩 명령 모음을 작성할 때 목적 또는 개념 프로세스를 설명하는 코드 주석을 포함하는 것이 도움이 될 수 있습니다. 미래의 자신에게 도움이 됩니다.
  • 애플리케이션에서 코드를 일시적으로 제거하여 다른 접근 방식을 시도하려고 하지만 아직 새 아이디어가 작동할지 확신하지 못하는 경우. 코드를 주석으로 처리하고 새 코드를 작성할 수 있으며 새 코드가 원하는 방식으로 작동할 것이라는 확신이 든다면 이전 코드(주석 처리된 코드)를 아무 문제 없이 삭제할 수 있습니다.
  • TODO와 같은 메시지를 추가하면 나중에 지정된 코드 경로를 확인하라는 메시지가 표시됩니다. 신중하게 사용해야 하긴 하지만 유용한 접근 방식입니다. 걱정을 불러일으키는 코드 줄을 읽을 때 다른 기능을 사용할 수 있습니다. 새 문제를 무시하는 대신 표시했다가 나중에 조사할 수 있습니다.

참고

코드 주석을 사용하여 코드에서 수행할 수 없는 내용을 말해야 합니다. 개발자는 코드는 종종 업데이트하면서도 코드 주석을 업데이트하는 것은 잊어버립니다. 간략한 아이디어에는 주석을 사용하고 개별 코드 줄의 작동 방식에 대한 주석은 추가하지 않는 것이 가장 좋습니다.

코딩 환경 준비

이 모듈에는 샘플 코드를 빌드하고 실행하는 과정을 안내하는 연습이 포함되어 있습니다. Visual Studio Code를 개발 환경으로 사용하여 이러한 활동을 완료하는 것이 좋습니다. 이러한 활동에 Visual Studio Code를 사용하면 전 세계 전문가가 사용하는 개발자 환경에서 코드를 더 편안하게 작성하고 실행하는 데 도움이 됩니다.

  1. Visual Studio Code를 엽니다.

    Windows 시작 메뉴(또는 다른 OS의 해당 리소스)를 사용하여 Visual Studio Code를 열 수 있습니다.

  2. Visual Studio Code의 파일 메뉴에서 폴더 열기를 선택합니다.

  3. 폴더 열기 대화 상자에서 Windows 바탕 화면 폴더로 이동합니다.

    코드 프로젝트를 유지하는 다른 폴더 위치가 있는 경우 해당 폴더 위치를 대신 사용할 수 있습니다. 이 학습에서는 쉽게 기억하고 찾을 수 있는 위치를 사용하는 것이 중요합니다.

  4. 폴더 열기 대화 상자에서 폴더 선택을 선택합니다.

    작성자를 신뢰하는지 묻는 보안 대화 상자가 표시되면 예를 선택합니다.

  5. Visual Studio Code 터미널 메뉴에서 새 터미널을 선택합니다.

    터미널 패널의 명령 프롬프트에 현재 폴더의 폴더 경로가 표시됩니다. 예를 들면 다음과 같습니다.

    C:\Users\someuser\Desktop>

    참고

    샌드박스 또는 호스트된 환경이 아닌 자체 PC에서 작업하고 이 C# 시리즈에서 다른 Microsoft Learn 모듈을 완료한 경우 이미 코드 샘플용 프로젝트 폴더를 만들었을 수 있습니다. 이 경우 TestProject 폴더에 콘솔 앱을 만드는 데 사용되는 다음 단계를 건너뛸 수 있습니다.

  6. 터미널 명령 프롬프트에서 지정된 폴더에 새 콘솔 애플리케이션을 만들려면 다음 프롬프트를 입력합니다.

    dotnet new console -o ./CsharpProjects/TestProject

    이 .NET CLI 명령은 .NET 프로그램 템플릿을 사용하여 지정된 폴더 위치에 새 C# 콘솔 애플리케이션 프로젝트를 만듭니다. 이 명령은 CsharpProjects 및 TestProject 폴더를 만들고 TestProject를 .csproj 파일의 이름으로 사용합니다.

    파일이 이미 있다는 메시지가 표시되면 다음 단계를 계속 진행합니다. 기존 프로젝트 파일을 다시 사용합니다.

  7. 탐색기 보기에서 CsharpProjects 폴더를 확장합니다 .

    TestProject 폴더와 두 개의 파일, 즉 Program.cs C# 프로그램 파일과 TestProject.csproj라는 C# 프로젝트 파일이 표시됩니다.

  8. Visual Studio Code의 파일 메뉴에서 폴더 열기를 선택합니다.

  9. 폴더 열기 대화 상자에서 CsharpProjects 폴더를 선택한 다음 폴더 선택을 선택합니다.

  10. 탐색기 보기에서 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. 탐색기 보기에서 TestProject 폴더 위치에서 터미널을 열려면 TestProject를 마우스 오른쪽 단추로 클릭한 다음 통합 터미널에서 열기를 선택합니다.

  6. 터미널 명령 프롬프트에서 dotnet run을 입력한 다음, Enter 키를 누릅니다.

    다음 출력이 표시됩니다.

    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 클래스 라이브러리의 작동 방식을 설명하는 코드 주석은 사용하지 않습니다.
  • 새 코드 솔루션을 커밋할 준비가 될 때까지 다른 솔루션을 일시적으로 시도할 때 코드 주석을 사용합니다. 이 시점에서 이전 코드를 삭제할 수 있습니다.
  • 주석을 신뢰하지 않습니다. 여러 번의 변경 및 업데이트를 거치고 나면 주석이 코드의 현재 상태를 반영하지 않을 수 있습니다.