对接口、实现或两者进行评论?

一般来说,我使用与代码相同的DRY(不要重复自己)原则:

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

Java专用 :在记录实现时,使用{@hericDoc}标签从接口中“包含”javadocs。

更多信息:

• Official javadoc documentation
• 一些非官方 advice .

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
{
    public int GetSiteID()
    {
        return CommonRepository.GetSiteID();
    }
}

官方参考 <inheritdoc /> : https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags#inheritdoc

只有界面。对两者都进行注释是重复的,如果代码发生变化,这两组注释最终可能会不同步。用“implements MyInterface”注释实现。..像Doxygen这样的东西无论如何都会生成将派生文档包含在实现文档中的文档(如果您正确设置的话)。

如果你使用 GhostDoc addin,当您右键单击并在方法上选择“DocumentThis”时,它会用界面中的注释更新实现。

对于C#,这取决于IMO:如果你使用显式接口实现,那么我就不会记录实现。

但是,如果你直接实现接口,并用你的对象公开接口的成员,那么这些方法也必须记录下来。

正如Nath所说,您可以使用GhostDoc将接口的文档自动插入到实现中。我将“文档此”命令映射到Ctrl+Shift+D快捷键及其几乎自动按下的按键之一。我相信ReSharper在为您实现方法时,也可以选择插入接口的文档。

注释接口应该有足够的文档来说明如何使用实际实现。我只会在实现中添加注释,前提是它插入了满足接口的私有函数,但这些注释仅限于内部,不会出现在在线文档中,也不会提供给客户端。

虽然看起来@Nath可能建议使用一个自动文档工具来帮助将事情放在一起(如果你使用它,听起来很酷)。在WhereIWorkAndYouDontCare,注释是针对开发人员的,因此最好在代码中放一个地方