코드 댓글 작성 : 코드 댓글을 인터페이스 나 콘크리트 클래스 또는 둘 다에 넣습니까? [복제하다

StackOverflow https://stackoverflow.com/questions/1875440

  •  18-09-2019
  •  | 
  •  

문제

이 질문은 이미 여기에 답이 있습니다.

클래스 및 인터페이스를 문서화하는 데있어 가장 모범 사례는 무엇입니까? FOO라는 구체적인 클래스가 있다면 ifoo라는 인터페이스에서 파생됩니다. 방법에 대한 의견을 어디에 넣습니까? 콘크리트 클래스뿐만 아니라 인터페이스에 대한 의견을 복제합니까?

다음은 주석이 복제되는 예입니다.

public class Foo : IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    public void DoSomething()
    {
    }
}

public interface IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    void DoSomething();
}
도움이 되었습니까?

해결책

나는 둘 다에 대해 의견을 넣을 것이다.

인터페이스에서는 인터페이스 멤버의 의도와 사용법에 대해 언급 할 것입니다.

구현에서는 특정 구현의 이유에 대해 언급 할 것입니다.

다른 팁

나는 일반적으로 그들을 두 가지 모두에 넣었지만 그들은 같은 말을하지 않습니다. 인터페이스의 주석은이 메소드/인터페이스의 추상적 목적을 설명해야합니다. 구체적인 의견은 인터페이스 목적의 맥락에서 메소드/클래스의 구현 세부 사항에 대해 이야기 할 것입니다.

나는 그것들을 둘 다 넣었지만, 의심 할 여지없이 나는 그것들을 인터페이스에만 넣었다.

코드를 사용할 때 툴팁이 마음에 들기 때문에이 작업을 수행합니다. 코드는 거의 항상 인터페이스를 사용해야합니다 ...

예제 코드는 명시 적 인터페이스 구현을 사용하지 않습니다. 코드의 클라이언트는 클래스 객체 또는 인터페이스 참조를 통해 메소드를 호출 할 수 있으므로 두 가지가 필요합니다. 명시 적 인터페이스 구현을 사용하면 클라이언트가 볼 수 없으므로 클래스 메소드 주석을 생략 할 수 있습니다. 이것은 XML 문서를 사용하여 IntellIsense 정보를 생성한다고 가정합니다.

둘 다하지만 동기화로 유지할 수있는 기능이 내장되어 있기를 바랍니다.

태그 <referTo>System. .... </referTo> 의견을 연결하는 것이 이상적입니다

나는 전혀 사용하지 않습니다. 대신 나는 코드를 구성하고 모든 방법과 변수의 이름을 언급하지 않고하는 일을 명백히 명시한 방식으로 이름을 지정해야합니다. 주석의 문제점은 컴파일하지 않고 실행되지 않으며 장치 테스트에 의해 테스트되지 않으므로 코드와 동기화하는 것은 거의 불가능합니다.

인터페이스에만 해당됩니다. 이 경우 동기화 할 필요가 없기 때문입니다. 내 IDE는 콘크리트 클래스에서 인터페이스 주석을 볼 수 있도록 도와줍니다. API 문서 생성기도 동일합니다.

이상적으로는 모든 구체적인 구현이 이행 해야하는 계약을 정의하기 때문에 인터페이스 만 문서화해야합니다.

라이센스 : CC-BY-SA ~와 함께 속성
제휴하지 않습니다 StackOverflow
scroll top