评论接口，实现或两者兼而有之？

interface java c# comments

2022-08-31 07:44:20

我想我们所有人（当我们可能被打扰时！）评论我们的界面。例如：

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

您是否还对实现进行了注释（也可以将其提供给客户端，例如作为库的一部分）？如果是这样，您如何管理保持两者的同步？或者您只是添加“请参阅文档界面”注释？

谢谢

答案 1

作为一般规则，我使用与代码相同的DRY（不要重复自己）原则：

在界面上，记录界面
关于实施，记录实施细节

Java特定：在记录实现时，使用{@inheritDoc}标签从接口“包含”javadocs。

欲了解更多信息：

官方 javadoc 文档
一些非官方的建议。

答案 2

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