评论接口、实现或两者? [英] 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);
}

您是否也对实现进行了评论(也可以提供给客户，例如作为库的一部分)?如果是这样，您如何管理保持两者同步?或者您只是添加了查看文档界面"的注释?

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?

谢谢

推荐答案

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

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 文档
• 一些非官方的建议.

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