[C#] 코드 문서화

Code Documentation

코드 문서화는 필요할 수도 있고, 아닐 수도 있다.

 

코드가 어떻게 작동하는지 그리고 코드를 어떻게 활용하는지 파악해야 할 때, 코드 문서는 유용하다. 코드 문서가 있으면 동료 개발자의 업무를 방해하지 않으면서, 코드를 이해할 수 있다. 즉 코드 문서는 코드와 작성자 간의 결합도를 줄여준다. 하지만 코드 문서는 생산성을 저하시키는 행정 업무로 변질되기 쉽상이다. 코드가 변경되면 문서를 같이 업데이트해야 한다. 즉 코드와 문서가 서로 결합된다.

 

코드 문서화는 생산성 증가를 보장하지 않는다. 따라서 문서화를 진행하기 전에 과연 코드를 문서화하는 작업이 생산성을 증가시킬 수 있는지 충분한 검토가 필요하다. 왜냐하면 코드 문서로 업무를 올바르고 정확하게 하는 것도 중요하지만, 업무를 기한 안에 적은 노력으로 완료하는 것 또한 중요하기 때문이다.

 

두마리 토끼를 잡는 방법은 코드 문서 대신 코드가 스스로를 설명할 수 있을 정도로 코딩 규칙에 따라 간결하고 명확하게 작성하는 것이다. 다른 개발자가 이해하기 쉽도록 클린한 코드를 작성하는 것이 코드를 문서화하는 것보다 효율적이고 깔끔한 방법이며, 문서 작업은 줄이고 개발 작업에 시간을 투자할 수 있다.

 

코드 문서가 생산성을 저해하는 대표적인 상황은 전체적인 설계가 직관적으로 이해하기 어려워, 코드 문서로 설계부터 구현까지 모든 내용을 설명할 때이다. 문서로 코드의 이해를 대체하여 코드가 읽기 어려워도 된다면, 생산성은 점점 저하되고 문서는 점점 정교해지는 어처구니 없는 사태가 발생한다.

 

따라서 코드 문서화는 최소한의 작업만 할 수 있도록 사전에 리팩토링 작업이 완료된 후에 진행하면 효율적인 작업이다. 특히 모든 코드를 문서화할 필요도 없다. public 으로 사용자에게 공개된 내용만 문서화하여도 충분하다.

 

<summary>요약된 정보</summary>

IntelliSense 또는 API reference 문서에서 참고하여, 표시되는 정보이므로 매우 중요하다.

 

/*
    The main Math class
    Contains all methods for performing basic math functions
*/
/// <summary>
/// The main Math class.
/// Contains all methods for performing basic math functions.
/// </summary>
public class Math
{
    // Adds two integers and returns the result
    /// <summary>
    /// Adds two integers and returns the result.
    /// </summary>
    public static int Add(int a, int b)
    {
        // If any parameter is equal to the max value of an integer
        // and the other is greater than zero
        if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0))
            throw new System.OverflowException();

        return a + b;
    }
}

 

<returns>함수 반환값</returns>

 

// Adds two integers and returns the result
/// <summary>
/// Adds two integers and returns the result.
/// </summary>
/// <returns>
/// The sum of two integers.
/// </returns>
public static int Add(int a, int b)
{
    // If any parameter is equal to the max value of an integer
    // and the other is greater than zero
    if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0))
        throw new System.OverflowException();

    return a + b;
}

 

<value>속성 설명</value>

 

public class Math
{
    /// <value>Gets the value of PI.</value>
    public static double PI { get; }
}

 

<example>예제 코드</example>

 

/// <example>
/// <code>
/// int c = Math.Add(4, 5);
/// if (c > 10)
/// {
///     Console.WriteLine(c);
/// }
/// </code>
/// </example>
public static int Add(int a, int b)
{
    // If any parameter is equal to the max value of an integer
    // and the other is greater than zero
    if ((a == int.MaxValue && b > 0) || (b == int.MaxValue && a > 0))
        throw new System.OverflowException();

    return a + b;
}

 

<exception>발생가능 예외</exception>

 

/// <summary>
/// Divides an integer by another and returns the result.
/// </summary>
/// <returns>
/// The division of two integers.
/// </returns>
/// <exception cref="System.DivideByZeroException">Thrown when a division by zero occurs.</exception>
public static int Divide(int a, int b)
{
    return a / b;
}

 

<see>다른 문서로 연결되는 링크</see>

 

/// <summary>
/// Adds two doubles and returns the result.
/// </summary>
/// <returns>
/// The sum of two doubles.
/// </returns>
/// <exception cref="System.OverflowException">Thrown when one parameter is max 
/// and the other is greater than zero.</exception>
/// See <see cref="Math.Add(int, int)"/> to add integers.
public static double Add(double a, double b)
{
    if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0))
        throw new System.OverflowException();

    return a + b;
}

 

<param name="이름">매개 변수 설명</param>

 

/// <param name="a">A double precision number.</param>
/// <param name="b">A double precision number.</param>
public static double Add(double a, double b)
{
    if ((a == double.MaxValue && b > 0) || (b == double.MaxValue && a > 0))
        throw new System.OverflowException();

    return a + b;
}

 

<typeparam name="제네릭 타입">제네릭 타입 설명</typeparam>

 

/// <summary>
/// Checks if an IComparable is greater than another.
/// </summary>
/// <typeparam name="T">A type that inherits from the IComparable interface.</typeparam>
public static bool GreaterThan<T>(T a, T b) where T : IComparable
{
    return a.CompareTo(b) > 0;
}

 

추가적인 태그는 마이크로소프트 공식문서 에서 확인하도록 하자.

XML 주석을 사용하여 코드 문서화

 

태그를 기반으로 문서를 생성할 때는 마이크로소프트에서 권장하는 DocFX를 활용하여 코드와 분리된 문서를 생성하도록 하자. docfx nuget package로 Visual Studio에 설치와 사용이 매우 간편하다. Quickstart를 참고하자.