인터페이스, 구현 또는 둘 다에 대해 코멘트하시겠습니까?

인터페이스, 구현 또는 둘 다에 대해 코멘트하시겠습니까?

(방해를 받을 수 있을 때!) 모두 인터페이스에 코멘트를 하고 있다고 생각합니다.

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

구현(라이브러리의 일부로서 클라이언트에 제공되는 경우도 있습니다)에 대해서도 코멘트를 해 주실 수 있습니까?그렇다면 어떻게 두 가지를 동기화시킬 수 있습니까?아니면 '설명서에 대한 인터페이스 참조' 코멘트만 추가하면 됩니까?

고마워요.

일반적으로 코드와 같은 DRY(Don't Repeat Yourself) 원칙을 사용합니다.

• 인터페이스 상에서 인터페이스를 문서화합니다.
• 구현 시 구현 세부 사항 문서화

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

상세한 것에 대하여는, 다음을 참조해 주세요.

• 공식 javadoc 문서
• 비공식적인 조언이 있습니다.

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();
    }
}

GhostDoc 추가 기능을 사용할 경우, 마우스 오른쪽 단추를 누르고 메서드에서 "문서 작성"을 선택하면 인터페이스에서 주석을 사용하여 구현을 업데이트합니다.

인터페이스만.코멘트는 모두 중복이며, 코드가 변경되면 최종적으로 2개의 코멘트가 동기화되지 않을 가능성이 있습니다.구현에 대해 "implements MyInterface"를 사용하여 코멘트합니다.Doxygen과 같은 것은 (올바르게 설정한 경우) 파생된 문서를 실장용 문서에 포함하는 문서를 생성합니다.

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

다만, 인터페이스를 직접 실장해, 인터페이스의 멤버를 오브젝트와 함께 공개하는 경우는, 이러한 방법도 문서화할 필요가 있습니다.

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

인터페이스에 코멘트를 다는 것은, 실제의 실장 사용 방법을 파악하기 위한 충분한 문서입니다.실장에 코멘트를 추가할 수 있는 것은, 인터페이스를 만족시키기 위해서 삽입된 프라이빗 기능이 있는 경우 뿐입니다만, 코멘트는 내부 전용이며, 온라인의 메뉴얼이나 클라이언트에 대해서는 표시되지 않습니다.

실장은 인터페이스에 준거하고 있는 한, 개별적으로 문서화할 필요는 없습니다.

인터페이스에 코멘트만 하면, 코멘트는 파생 클래스 또는 베이스 클래스/인터페이스와 동기화되기 쉬워지기 때문에, 1개의 장소에 코멘트를 두는 것은 매우 편리합니다.

@Nath처럼 보이지만, 모든 것을 하나로 유지하는 데 도움이 되는 자동 문서 도구를 제안할 수도 있습니다(사용하는 경우 쿨하게 들릴 수 있습니다).이쪽의 장소IWork And You DontCare의 코멘트는 개발용이므로 코드에서 한 자리만 사용하는 것이 좋습니다.

물론 둘 다 코멘트할 수 있지만 (앞에서 설명한 바와 같이) 둘 다 유지 보수해야 하는 문제가 발생합니다.하지만, 요즘 시대에 IOC/DI를 사용하지 않고 인터페이스를 사용하지 않는 소비 코드가 있을까요?이 때문에 굳이 코멘트를 하고 싶은 경우는, 인터페이스에 코멘트를 하는 것을 강하게 추천합니다.이렇게 하면 코드 소비자는 훌륭한 인텔리센스 힌트를 얻을 수 있을 것입니다.

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

소스 코드의 Intellissense에는 도움이 되지 않지만 수정된 XML 문서 파일을 NuGet 패키지에 포함할 수 있으므로 참조된 NuGet 패키지의 Intellissense와 함께 사용할 수 있습니다.

www.inheritdoc.io (무료판 이용 가능)

언급URL : https://stackoverflow.com/questions/759703/comment-the-interface-implementation-or-both