如何在C#中评论/记录覆盖?

时间:2012-03-28 20:48:50

标签: c# inheritance comments override xml-documentation

有时候我会覆盖基类中的方法。有时我甚至用空方法覆盖它们,因为我想要的是防止这种行为。

在过去,我会写这样的内容来显示绕过基本方法的意图

protected override void OnMouseUp(MouseEventArgs e)
{
    // base.OnMouseUp(e);
}

(我知道注释的代码行是一件坏事。我使用来做这件事)

但我想做得更好:

  • 如何记录覆盖的意图?具体来说:
  • 我在覆盖的XML <summary>?)文档中写了什么?

3 个答案:

答案 0 :(得分:5)

对于文档,我只想使用built-in documentation tags

/// <summary>Exiting drag mode on mouse up</summary>
protected override void OnMouseUp(MouseEventArgs e)
{
    ...

为澄清意图,我只想发表评论,如

protected override void OnMouseUp(MouseEventArgs e)
{
    // not calling the base implementation
    ...
}

该行

// base.OnMouseUp(e);

给人的印象是暂时注释了这个电话(可能还有人忘了恢复它)

答案 1 :(得分:3)

这样的评论
// This method is intentionally blank because 
// we do not want the base class functionality

好多了
// base.SomeMethod();

第一条评论清楚地说明了你为什么做了你所做的事情,下一位开发人员不必怀疑对基本方法的调用是否被意外注释掉了。

如果您可以控制基类,那么删除该方法并使该类更抽象可能会更好。然后,您可以选择仅在需要它的子类中实现该功能。

答案 2 :(得分:1)

在我看来,评论基类调用确实与使意图明确相反。人们会想知道为什么注释行仍然存在,以及它是否仍然有用,因为你没有删除它。所以我会删除注释掉的行。

您可以像任何其他方法一样记录覆盖,并在文档中指定为什么将方法保留为空。您可以将原因写入方法体中作为注释,我想这是一个偏好问题。

我认为这取决于此信息是否仅对维护代码的开发人员或代码用户(例如您的库的用户)很重要。对于通常仅由操作系统调用的事件(如在您的示例中),将其放在摘要标记中并不是必需的。

但是,如果您需要覆盖方法来禁用基类的行为,那么您可能应该重新考虑设计的那一部分。这种行为对我来说似乎有点不直观。