评论界面,实现或两者?


问题内容

我想象我们所有人(当我们可以打扰的时候!)评论我们的界面。例如

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

您是否也评论了实现(它也可能作为一个库的一部分提供给客户)?如果是这样,您如何管理两者同步?还是只是添加“查看文档界面”注释?

谢谢


问题答案:

作为一般规则,我使用与代码相同的DRY(不重复自己)原理:

  • 在界面上,记录界面
  • 在实施过程中,记录实施细节

特定于Java的 文档:在记录实现时,请使用{@inheritDoc}标记从界面“包括” javadocs。

想要查询更多的信息: