c # /. net에서 예외를 문서화하는 방법

현재 회사 내의 다른 개발자가 내부적으로 사용할 작은 프레임 워크를 작성하고 있습니다.

좋은 Intellisense 정보를 제공하고 싶지만 발생한 예외를 문서화 하는 방법 을 잘 모르겠습니다 .

다음 예에서

public void MyMethod1()
{
    MyMethod2();

    // also may throw InvalidOperationException
}

public void MyMethod2()
{
    System.IO.File.Open(somepath...); // this may throw FileNotFoundException

    // also may throw DivideByZeroException
}

예외 문서화에 대한 마크 업은 다음과 같습니다.

/// <exception cref="SomeException">when things go wrong.</exception>

내가 이해하지 못하는 것은에 의해 호출 된 코드에 의해 발생하는 예외를 문서화하는 방법입니다 MyMethod1().

• 예외를 문서화해야합니까? MyMethod2()
• 발생한 예외를 문서화해야합니까 File.Open()?

가능한 예외를 문서화하는 가장 좋은 방법은 무엇입니까?

호출 할 수있는 메소드의 예외를 포함하여 코드에서 발생할 수있는 모든 예외를 문서화해야합니다.

목록이 약간 커지면 자체 예외 유형을 만들 수 있습니다. 메소드 내에서 발생할 수있는 모든 것을 잡아서 예외로 감싸서 던지십시오.

이 방법으로 수행 할 수있는 또 다른 장소는 메소드가 API에있는 경우입니다. 파사드가 여러 인터페이스를 단일 인터페이스로 단순화하는 것처럼 API는 여러 예외를 단일 예외로 단순화해야합니다. 발신자가 더 쉽게 코드를 사용할 수 있습니다.

Andrew의 우려에 대한 답변 (댓글)에는 세 가지 유형의 예외가 있습니다. 알지 못하는 것, 알지 못하고 할 수없는 것, 알거나 할 수있는 것에는 예외가 있습니다.

당신이 모르는 사람들은 떠나고 싶어합니다. 빠른 실패의 원칙은 데이터가 손상 될 수있는 상태에 들어가는 것보다 앱이 중단되는 것보다 낫습니다. 충돌은 발생한 상황과 이유를 알려주며 "알지 못하는 사람"목록에서 해당 예외를 제거하는 데 도움이 될 수 있습니다.

당신이 알고 있고 할 수없는 것은 OutOfMemoryExceptions와 같은 예외입니다. 극단적 인 경우에는 이와 같은 예외를 처리하고 싶을 수도 있지만, 매우 놀라운 요구 사항이 없으면 예외를 첫 번째 범주처럼 취급해야합니다. 당신 은 가지고 있습니까 이러한 예외를 문서화? 객체를 새로 만드는 모든 단일 메소드에서 OOM을 문서화하는 것은 어리석은 것처럼 보일 것입니다.

당신이 알고 있고 할 수있는 것은 문서화하고 포장해야하는 것들입니다.

예외 처리에 대한 추가 지침은 여기에서 찾을 수 있습니다 .

표준 xml 문서를 사용해야합니다 .

/// <exception cref="InvalidOperationException">Why it's thrown.</exception>
/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
/// <exception cref="DivideByZeroException">Why it's thrown.</exception>
public void MyMethod1()
{
    MyMethod2();
    // ... other stuff here
}

/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
/// <exception cref="DivideByZeroException">Why it's thrown.</exception>
public void MyMethod2()
{
    System.IO.File.Open(somepath...);
}

/// <exception cref="FileNotFoundException">Why it's thrown.</exception>
public void MyMethod3()
{
    try
    {
        MyMethod2();
    }
    catch (DivideByZeroException ex)
    {
        Trace.Warning("We tried to divide by zero, but we can continue.");
    }
}

이 방법으로 수행 할 수있는 값은 발생할 수있는 알려진 예외에 대한 문서를 제공한다는 것입니다. 이 문서는 Visual Studio를 사용하는 경우 인텔리전스로 제공되며 나중에 예상 할 수있는 예외를 상기시킬 수 있습니다.

한 가지 유형의 예외를 처리 할 수있는 반면 다른 유형은 심각한 문제의 결과이므로 수정할 수 없으므로 특정 예외 유형을 지정하려고합니다.

몇 가지 훌륭한 추가 기능을 사용하여 문서 프로세스를보다 쉽게 ​​만들 수 있습니다. 그중 하나가 XML 문서 주석을 생성하는 Visual Studio 용 무료 애드 인 GhostDoc 입니다. 또한 ReSharper 를 사용하는 경우 예외가 발생했을 때 XML 주석을 생성하는 옵션이 추가 된 뛰어난 ReSharper 용 Agent Johnson 플러그인 을 살펴보십시오 .

업데이트 : 카발라 존슨 R # 8을 사용할 수없는 것으로 보인다는 체크 아웃 ReSharper에서 탁월한 대안으로 ...

1 단계 : GhostDoc은 XML 주석 (Ctrl-Shift-D)을 생성하는 반면 ReSharper 용 에이전트 Johnson 플러그인은 예외 문서화도 제안합니다.

2 단계 : ReSharper의 바로 가기 키 (Alt-Enter)를 사용하여 예외 문서를 추가하십시오.

2 단계 http://i41.tinypic.com/osdhm

희망이 있습니다 :)

내가 이해 한 것에서 <exception> 요소를 사용하려는 의도는 예외가 아닌 메소드를 장식 할 때 사용하는 것입니다.

/// <summary>Does something!</summary>
/// <exception cref="DidNothingException">Thrown if nothing is actually done.</exception>
public void DoSomething()
{
// There be logic here
}

호출 된 다른 메소드에서 발생할 수있는 예외는 해당 메소드에서 포착, 처리 및 문서화되어야합니다. .NET에서 발생할 수있는 예외 또는 사용자 고유 코드에서 명시 적으로 발생한 예외를 문서화해야합니다.

그것보다 더 구체적으로하는 한, 당신은 아마도 자신만의 맞춤형 예외를 잡을 수 있습니까?

방법에 대한 계약의 일부는 전제 조건이 유효한지 확인하는 것입니다.

public void MyMethod2()
{
    System.IO.File.Open(somepath...); // this may throw FileNotFoundException
}

된다

/// <exception cref="FileNotFoundException">Thrown when somepath isn't a real file.</exception>
public void MyMethod2()
{
    FileInfo fi = new FileInfo( somepath );
    if( !fi.Exists )
    {
        throw new FileNotFoundException("somepath doesn't exists")
    }
    // Maybe go on to check you have permissions to read from it.

    System.IO.File.Open(somepath...); // this may still throw FileNotFoundException though
}

이 방법을 사용하면 발생 OutOfMemoryException 가능성 등을 문서화하지 않고도 명시 적으로 던지는 모든 예외를 문서화하는 것이 더 쉽습니다 .

메소드에서 발생할 수있는 모든 예외를 문서화해야합니다.

구현 세부 사항을 숨기려면 MyMethod2의 일부 예외를 직접 처리하려고합니다.

예외를 처리하거나 해결할 수없는 경우 레트로 윙을 고려할 수 있습니다. 대부분의 경우 호출자에게 더 의미있는 예외로 패키지 / 랩핑됩니다.

실제로 이미 답변을 마쳤으므로 예외를 문서화하는 방법은 XML 주석을 사용하는 것입니다.

플러그인 외에도 TFS와 통합 될 수있는 정적 분석 도구를 사용하여 예외를 문서화 할 수 있습니다.

아래 링크에서 메소드가 문서화 한 예외를 검증하기 위해 StyleCop에 대한 사용자 정의 규칙을 작성하는 방법을 볼 수 있습니다.

http://www.josefcobonnin.com/post/2009/01/11/Xml-Documentation-Comments-Exceptions-I.aspx http://www.josefcobonnin.com/post/2009/01/15/Xml-Documentation -의견-예외 -II.aspx

문안 인사.

메소드에 예상되는 예외를 문서화하십시오. 예제에서 해당 메소드가 파일을 찾을 수 없음 예외를 던질 수 있음을 사용자에게 알려줍니다.

발신자에게 처리 방법을 선택할 수 있도록 예상 대상을 알려주는 것입니다.