C#으로 코드 문서화

오 소년, 다시 그 시간입니다. 새 기능을 작성할 때 코드를 문서화해야 한다는 사실을 깨닫고 두려움을 느낀 적이 있습니까?

우리는 모두 거기에 있었습니다. 하지만 이 가이드가 코드베이스 전체에 걸쳐 문서를 표준화하려는 어려움을 완화하는 데 도움이 되기를 바랍니다.

먼저 C# Intellisense가 제안 주석을 처리하는 방법을 설정해야 합니다. 형식은 주석 처리된 코드의 XML과 유사합니다. 메서드/클래스/필드를 문서화하는 데 도움이 되는 많은 특수 태그가 있지만 실제로 중요한 것은 몇 가지뿐입니다.

내 생각에 가장 중요한 태그는 <summary> 태그입니다. 이 태그를 사용하면 코드가 수행하는 작업을 요약할 수 있습니다. 예를 들어 간단한 방법을 만들어 봅시다.

이 메서드는 정수를 매개변수로 사용하고 값을 두 배로 반환합니다.

public int Double(int i)
{
    return i * 2;
}

요약 태그를 추가하면 다음과 같이 표시됩니다.

/// <summary>Doubles an integer.</summary>
public int Double(int i)
{
    return i * 2;
}

Double()와 상호 작용하는 개발자의 경우 다음과 같이 표시됩니다.



두 번째로 중요한 태그는 <value> 태그입니다. 이제 이 태그는 실제로 필드에만 적용되며 기본적으로 변수에 대한 요약입니다.

예:

/// <value>The value of 2 doubled.</value>
public int DoubledNumber = Double(2);

개발자가 보는 것:



마지막에서 두 번째로 필요한 태그는 <returns> 태그입니다. 이 태그의 사용은 이름 그대로입니다(메서드가 반환하는 내용에 대해 알려줌).
Double()로 돌아가서 예를 들면 다음과 같습니다.

/// <summary>Doubles an integer.</summary>
/// <returns>An integer.</returns>
public int Double(int i)
{
    return i * 2;
}

개발자가 보는 것:



정보가 쌓이기 시작하는 방법에 주목하십시오. 이것이 내가 메서드당 몇 개의 태그만 갖는 것을 선호하는 이유 중 하나입니다. 우리는 사소한 정보로 개발자를 압도하고 싶지 않습니다.

마지막으로 논의할 태그는 <param> 태그입니다. 이것은 다른 것과 약간 다른 방식으로 사용되므로 주의하십시오. 기본적으로 태그는 메서드의 각 개별 매개 변수에 대한 정보를 제공하는 데 사용됩니다.

예:

/// <summary>Doubles an integer.</summary>
/// <returns>An integer.</returns>
/// <param name="i">The integer to double.</param>
public int Double(int i)
{
    return i * 2;
}

개발자가 보는 것:


<param> 태그를 한 번만 사용했지만 원하는 만큼 많은 매개변수에 대해 스택할 수 있습니다.

이제 기본 태그를 살펴보았으므로 댓글 시스템이 작동하는 방식에 대한 일반적인 이해가 있어야 합니다. 더 많은 태그에 대해 알아보려면 this Microsoft reference 문서가 잘 작동한다는 것을 알았습니다.

읽어 주셔서 감사합니다!