인터페이스, 구현 또는 둘 다를 언급하십니까?

나는 우리 모두가 (우리가 귀찮게 할 수있을 때!) 우리의 인터페이스에 대해 논평한다고 상상한다. 예 :

/// <summary>
/// Foo Interface
/// </summary>
public interface Foo
{
    /// <summary>
    /// Will 'bar'
    /// </summary>
    /// <param name="wibble">Wibble factor</param>
    void Bar(string wibble);
}

당신은 또한 구현 (예를 들어 라이브러리의 일부로서 클라이언트에게 제공 될 수있는)에 대해서도 언급하고 있습니까? 그렇다면 둘을 동기화 상태로 유지하는 방법은 무엇입니까? 아니면 '문서의 인터페이스 참조'주석 만 추가 하시겠습니까?

감사

일반적으로 코드와 동일한 DRY (Do n't Repeat Yourself) 원칙을 사용합니다.

• 인터페이스에서 인터페이스를 문서화하십시오.
• 구현시 구현 세부 사항을 문서화하십시오.

Java 전용 : 구현을 문서화 할 때 {@inheritDoc} 태그를 사용하여 인터페이스에서 javadoc을 "포함"하십시오.

자세한 내용은:

• 공식 javadoc 문서
• 비공식 조언 .

GhostDoc 애드 인 을 사용하는 경우 , 마우스 오른쪽 버튼을 클릭하고 메소드에서 "Document This"를 선택하면 인터페이스의 주석으로 구현이 업데이트됩니다.

C #의 경우 IMO에 의존합니다. 명시 적 인터페이스 구현을 사용하는 경우 구현을 문서화하지 않습니다.

그러나 인터페이스를 직접 구현하고 객체의 인터페이스 멤버를 노출하는 경우 이러한 메소드도 문서화해야합니다.

Nath가 말했듯이 GhostDoc을 사용하여 인터페이스 문서를 구현에 자동으로 삽입 할 수 있습니다. 문서이 명령을 Ctrl + Shift + D 바로 가기와 거의 자동으로 누르는 키 입력 중 하나에 매핑했습니다. 또한 ReSharper는 메소드를 구현할 때 인터페이스 문서를 삽입 할 수있는 옵션도 있다고 생각합니다.

인터페이스 만. 둘 다 주석 처리는 중복되며 코드가 변경되면 두 주석 세트가 결국 동기화되지 않을 수 있습니다. "구현 MyInterface"로 구현에 주석을 답니다. Doxygen과 같은 것들은 파생 문서를 구현 문서에 포함하는 문서를 생성합니다.

우리는 단지 인터페이스에 주석을 달고, 주석은 파생 또는 기본 클래스 / 인터페이스와 동기화하기가 너무 쉽습니다. 단지 한 곳에 배치하는 것이 좋습니다.

@Nath처럼 보이지만 물건을 함께 보관하는 데 도움이되는 자동화 된 문서 도구를 제안 할 수도 있습니다 (사용하면 멋지게 들립니다). 여기서 WhereIWorkAndYouDontCare에서는 주석이 dev 용이므로 코드의 단일 위치가 선호됩니다.

인터페이스를 주석 처리하면 실제 구현을 사용하는 방법을 파악하기에 충분한 문서가 있어야합니다. 구현에 주석을 추가 할 수있는 유일한 시간은 인터페이스를 만족시키기 위해 삽입 된 개인 함수가있는 경우이지만 내부 주석 일 뿐이며 온라인 설명서 또는 클라이언트가 사용할 수없는 주석입니다.

인터페이스를 준수하는 한 별도로 문서화 할 필요가 없습니다.

<inheritdoc /> 태그에 대한 지원을 추가하기 위해 XML 문서 파일을 사후 처리하는 도구를 만들었습니다.

소스 코드에서 Intellisense를 지원하지는 않지만 수정 된 XML 문서 파일을 NuGet 패키지에 포함 할 수 있으므로 참조 된 NuGet 패키지에서 Intellisense와 함께 작동합니다.

www.inheritdoc.io에 있습니다 (무료 버전 사용 가능).

확실히 두 가지 모두를 언급 할 수 있지만 두 가지를 유지하는 데 문제가 있습니다 (앞서 언급 한 것처럼). 그러나 요즘에는 소비 코드가 실제로 IoC / DI를 사용하지 않고 인터페이스를 사용하지 않습니까? 만약 당신이 하나의 주석을 귀찮게하고 싶다면 인터페이스에 주석을 달 것을 강력히 권합니다. 이렇게하면 코드 소비자가 좋은 지능 힌트를 얻을 가능성이 높습니다.

C # 사용법 :

인터페이스는 다음과 같습니다.

    /// <summary>
    /// Helper class to access various properties for the current site.
    /// </summary>
    public interface ISiteHelper
    {
        /// <summary>
        /// Gets the site id of the current site
        /// </summary>
        /// <returns>The site id.</returns>
        int GetSiteID();
    }
}

구현은 다음과 같습니다.

/// <inheritdoc />
public class SiteHelper: ISiteHelper
{
    /// <inheritdoc />
    public int GetSiteID()
    {
        return CommonRepository.GetSiteID();
    }
}