C# 주석 마스터하기: 종류, 모범 사례, XML 문서화

C# 주석(Comments)

이 글에서는 C# 주석의 종류, 스타일, 그리고 프로그램에서 효과적으로 사용하는 이유와 방법을 배웁니다.

주석은 읽기 쉬운 코드의 생명선입니다. 의도를 설명하고, 복잡한 로직을 명확히 하며, 설계 결정을 문서화하는 사람 읽기 좋은 주석입니다. 컴파일러는 완전히 무시하므로 런타임 성능에 영향을 주지 않습니다.

마이크로소프트 공식 문서에 따르면 C#은 세 가지 주요 주석 스타일을 지원합니다:

1. 한 줄 주석 (//)
2. 여러 줄 주석 (/* */)
3. XML 문서화 주석 (///)

---

한 줄 주석 (Single-Line Comments)

한 줄 주석은 이중 슬래시 //로 시작하여 줄 끝까지 이어집니다. // 뒤의 모든 내용은 컴파일러가 무시합니다.

int a = 5 + 7; // 5와 7 더하기

여기서 5와 7 더하기가 주석입니다.

예제 1: 한 줄 주석 사용

// Hello World 프로그램
using System;
namespace HelloWorld {
    class Program {
        public static void Main(string[] args) // 실행은 Main 메서드부터 시작
        {
            // Hello World 출력
            Console.WriteLine("Hello World!");
        }
    }
}

위 프로그램에는 세 개의 한 줄 주석이 있습니다:

// Hello World 프로그램
// 실행은 Main 메서드부터 시작
// Hello World 출력

코드와 같은 줄에 주석을 달 수 있지만, 모범 사례는 주석을 별도 줄에 두어 가독성을 높이는 것입니다.

---

여러 줄 주석 (Multi-Line Comments)

여러 줄 주석은 /*로 시작하여 */로 끝납니다. 여러 줄에 걸쳐 쓸 수 있어 블록 설명이나 코드 임시 비활성화에 적합합니다.

예제 2: 여러 줄 주석 사용

/* 이는 C# Hello World 프로그램입니다.
   이 프로그램은 Hello World를 출력합니다. */
using System;
namespace HelloWorld {
    class Program {
        public static void Main(string[] args) {
            /* Hello World 출력 */
            Console.WriteLine("Hello World!");
        }
    }
}

프로그램에는 두 개의 여러 줄 주석이 포함됩니다:

/* 이는 C# Hello World 프로그램입니다.
   이 프로그램은 Hello World를 출력합니다. */
/* Hello World 출력 */

단일 /* … */ 블록으로 한 줄 주석을 대체할 수도 있습니다.

---

XML 문서화 주석 (XML Documentation Comments)

XML 문서화 주석은 세 개의 슬래시 ///로 시작하며, 구조화된 메타데이터를 코드에 직접 포함할 수 있게 합니다. 이 주석은 Visual Studio 같은 도구에서 추출되어 외부 XML 문서 파일을 생성하며, IntelliSense 툴팁이나 문서 생성기에 활용됩니다.

XML에 익숙하지 않다면 XML이란?을 참조하세요.

예제 3: XML 문서화 주석 사용

/// <summary>
/// 이는 Hello World 프로그램입니다.
/// </summary>
using System;
namespace HelloWorld {
    class Program {
        public static void Main(string[] args) {
            Console.WriteLine("Hello World!");
        }
    }
}

예제의 XML 주석:

/// <summary>
/// 이는 Hello World 프로그램입니다.
/// </summary>

생성된 XML 파일 예시:

<?xml version="1.0"?>
<doc>
  <assembly>
    <name>HelloWorld</name>
  </assembly>
  <members>
  </members>
</doc>

더 깊은 내용은 XML 문서화 주석을 참조하세요.

---

주석 올바르게 활용하기

효과적인 주석은 코드를 어지럽히지 않으면서 의도를 명확히 합니다. 과도한 주석은 로직을 가리고, 부족한 주석은 유지보수를 어렵게 만듭니다.

다음 예시:

// Hello World 출력
Console.WriteLine("Hello World");

이 코드는 자명하므로 주석이 중복됩니다. 대신 주석은 다음에 활용하세요:

• 명백하지 않은 알고리즘이나 비즈니스 로직 설명
• 가정, 예외 상황, 잠재적 함정 강조
• 블록의 목적을 '어떻게'가 아닌 '왜'에 초점을 맞춰 간략히 설명

기억하세요: 간결하고 목적 있는 주석이 전문적인 코드베이스의 특징입니다.