注释的接口，实现或两者兼而有之？ [英] Comment the interface, implementation or both?

问题描述

我想，我们都（何时才能被人打扰！）发表评论我们的接口。 。例如

I imagine that we all (when we can be bothered!) comment our interfaces. e.g.

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

你也评论了实现（也可以被提供给客户，例如为AA库的一部分）？如果是这样，你如何管理保持二者的同步？或者你只需​​要添加一个'见文档界面有何评论？

Do you also comment the implementation (which may also be provided to clients, e.g. as part of a a library)? If so how do you manage keeping the two in sync? Or do you just add a 'See interface for documentation' comment?

感谢

推荐答案

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

As a general rule, I use the same DRY (Don't Repeat Yourself) principle as with code:

• 在接口，文件接口


• 在实施中，文件的执行细节

的Java具体：记录的执行情况时，使用{} @inheritDoc标签包括从接口的javadoc

Java specific: when documenting the implementation, use {@inheritDoc} tag to "include" javadocs from the interface.

有关信息。

• 的官方Javadoc文档


• 一些非官方的建议。

• Official javadoc documentation
• Some unofficial advice.

这篇关于注释的接口，实现或两者兼而有之？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！