评论界面,实现或两者?
问题内容:
我想象我们所有人(当我们可以打扰的时候!)评论我们的界面。例如
/// <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。
想要查询更多的信息:
- 官方JavaDoc文档
- 一些非正式的建议。