C# 주석 종류와 작성법 - 심화

실무에서는 코드의 명확성, 협업 효율성, 유지보수성을 높이기 위해 주석과 XML 주석을 적절히 활용해야 합니다. 아래에 실무에서 자주 사용하는 주석 패턴과 실제 활용 예제를 제공합니다.

---

1. 실무에서 주석의 활용 기준

1.1. 주석이 필요한 경우

1. 복잡한 비즈니스 로직: 코드만으로는 이해하기 어려운 로직을 설명.
2. 기술적 결정의 근거: 특정 구현 방식이나 라이브러리를 선택한 이유.
3. 향후 유지보수 참고 사항: TODO, FIXME, HACK 등.

1.2. 주석이 불필요한 경우

1. 코드가 주석 없이도 명확한 경우.
2. 주석이 코드와 중복되거나 변경 가능성이 높은 경우.
3. 간단한 getter/setter나 DTO 클래스에는 주석 생략 가능.

---

2. 실무에서 주석 활용 예제

2.1. 비즈니스 로직 설명

/// <summary>
/// 고객 등급에 따라 할인을 계산합니다.
/// </summary>
/// <param name="customerType">고객 등급 (e.g., Regular, Premium)</param>
/// <param name="totalAmount">총 구매 금액</param>
/// <returns>할인 적용 후 금액</returns>
public decimal CalculateDiscount(string customerType, decimal totalAmount)
{
    // Premium 고객은 10% 할인
    if (customerType == "Premium")
    {
        return totalAmount * 0.9m;
    }
    // Regular 고객은 할인 없음
    return totalAmount;
}

2.2. 기술적 결정 주석

// 왜 Newtonsoft.Json 대신 System.Text.Json을 사용하는가?
// - 성능 향상
// - .NET Core/Framework와의 호환성
// - 유지보수 비용 절감

2.3. TODO와 FIXME

• TODO: 구현 예정인 기능
• FIXME: 임시로 작성된 코드나 개선해야 할 부분

// TODO: 다국어 지원 추가 (현재는 기본 언어만 지원)
public string GetLocalizedText(string key)
{
    return resourceDictionary[key];
}

// FIXME: 임시로 하드코딩된 값. 환경 설정에서 읽어오도록 수정 필요
string connectionString = "Server=myserver;Database=mydb;User=myuser;Password=mypassword;";

---

3. XML 주석을 활용한 API 문서화

실무에서는 API를 작성할 때 IntelliSense와 자동 문서 생성을 위해 XML 주석을 적극 활용합니다.

3.1. Controller 클래스 주석

/// <summary>
/// 고객 관리 API 컨트롤러입니다.
/// </summary>
[ApiController]
[Route("api/[controller]")]
public class CustomerController : ControllerBase
{
    /// <summary>
    /// 모든 고객 목록을 조회합니다.
    /// </summary>
    /// <returns>고객 목록</returns>
    [HttpGet]
    public IEnumerable<Customer> GetAllCustomers()
    {
        // 데이터베이스에서 고객 목록 조회
        return _customerService.GetAll();
    }

    /// <summary>
    /// 특정 고객의 상세 정보를 조회합니다.
    /// </summary>
    /// <param name="id">고객 ID</param>
    /// <returns>고객 상세 정보</returns>
    /// <exception cref="NotFoundException">고객이 존재하지 않을 경우</exception>
    [HttpGet("{id}")]
    public ActionResult<Customer> GetCustomerById(int id)
    {
        var customer = _customerService.GetById(id);
        if (customer == null) throw new NotFoundException("Customer not found.");
        return customer;
    }
}

---

3.2. 비즈니스 계층 주석

/// <summary>
/// 고객 데이터 관련 비즈니스 로직을 처리하는 클래스입니다.
/// </summary>
public class CustomerService : ICustomerService
{
    private readonly ICustomerRepository _repository;

    /// <summary>
    /// 새 인스턴스를 초기화합니다.
/// </summary>
/// <param name="repository">고객 저장소 인터페이스</param>
    public CustomerService(ICustomerRepository repository)
    {
        _repository = repository;
    }

    /// <summary>
    /// 모든 고객 목록을 반환합니다.
/// </summary>
/// <returns>고객 목록</returns>
    public IEnumerable<Customer> GetAll()
    {
        return _repository.GetAll();
    }

    /// <summary>
    /// ID로 고객을 조회합니다.
/// </summary>
/// <param name="id">고객 ID</param>
/// <returns>고객 정보</returns>
/// <exception cref="ArgumentException">유효하지 않은 ID</exception>
    public Customer GetById(int id)
    {
        if (id <= 0) throw new ArgumentException("Invalid ID");
        return _repository.GetById(id) ?? throw new NotFoundException();
    }
}

---

4. 코드 리뷰에서 주석이 필요한 경우

4.1. 복잡한 알고리즘

/// <summary>
/// 두 문자열의 레벤슈타인 거리(편집 거리)를 계산합니다.
/// </summary>
/// <param name="s1">첫 번째 문자열</param>
/// <param name="s2">두 번째 문자열</param>
/// <returns>레벤슈타인 거리</returns>
public int CalculateLevenshteinDistance(string s1, string s2)
{
    int[,] dp = new int[s1.Length + 1, s2.Length + 1];

    // DP 테이블 초기화
    for (int i = 0; i <= s1.Length; i++) dp[i, 0] = i;
    for (int j = 0; j <= s2.Length; j++) dp[0, j] = j;

    // DP 알고리즘 수행
    for (int i = 1; i <= s1.Length; i++)
    {
        for (int j = 1; j <= s2.Length; j++)
        {
            // 문자가 같으면 비용 0, 다르면 1
            int cost = (s1[i - 1] == s2[j - 1]) ? 0 : 1;

            // 최소 비용 계산
            dp[i, j] = Math.Min(
                Math.Min(dp[i - 1, j] + 1, dp[i, j - 1] + 1),
                dp[i - 1, j - 1] + cost
            );
        }
    }

    return dp[s1.Length, s2.Length];
}

---

5. XML 주석으로 자동 문서 생성

5.1. XML 문서 파일 생성

1. Visual Studio에서 프로젝트 속성 → 빌드 → XML 문서 파일 체크.
2. 빌드 후 XML 파일 생성.

5.2. 문서 생성 도구 활용

• Sandcastle: XML 주석을 기반으로 HTML 문서 생성.
• DocFX: REST API, .NET 문서를 생성할 때 유용.

---

6. 마무리: 주석 작성 Best Practices

• 의도를 명확히: "왜 이 코드를 작성했는가?"에 초점.
• 갱신 필수: 코드 변경 시 주석도 함께 업데이트.
• 일관성 유지: 팀 내 주석 작성 규칙 정의.
• 과하지 않게: 너무 많은 주석은 유지보수를 방해할 수 있음.

이런 방식으로 주석을 작성하면 협업이 원활해지고 코드의 가독성과 유지보수성이 크게 향상됩니다.