属性的XML文档中是否需要“获取或设置..”？

19

我正在寻找有关C＃中XML注释的最佳实践的建议。创建属性时，预期的XML文档似乎具有以下形式：

/// <summary>
/// Gets or sets the ID the uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

但是，因为该属性的签名已经告诉您该类的外部客户端可以进行哪些操作（在这种情况下，这两个操作都是get和set），所以我觉得注释太闲谈了，也许以下内容就足够了：

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID {
    get;
    set;
}

Microsoft使用第一种形式，因此这似乎是一个隐含约定。但是我认为由于我所说的原因，第二种更好。

我知道此问题很容易被标记为非建设性的，但是必须评论的属性数量巨大，因此我相信这个问题有权解决。

我将不胜感激任何想法或与官方推荐做法的链接。

c# .net programming-practices comments

— 托马斯
source

老实说，注释给我的代码中没有的唯一内容（假设它是User的成员）是id是唯一的。所以没有一个是“必要的”。

— jk。

@Tomas-您是否安装了GhostDoc插件？如果您使用良好的属性名称开头并根据属性访问器自动放置gets or sets或，它将为您生成良好的XML注释gets。

— Trevor Pilley

@Trevor-我已经安装了它。我只是在考虑是否应该更改其模板并删除“获取或设置” ：）。它是一个很棒的插件。

— 托马斯

欢迎来到无证件的世界。

— 上校恐慌

28

签名可以告诉其他代码哪些操作可用。但是，编码人员在工作时并未清楚地看到它们，XML文档是供人们使用的，而不是编译器。

以此类为例：

public class MyClass
{
    /// <summary>
    /// The first one
    /// </summary>
    public int GetOrSet { get; set; }

    /// <summary>
    /// The second one
    /// </summary>
    public int GetOnly { get; private set; }

    /// <summary>
    /// The last one
    /// </summary>
    public int SetOnly { set; private get; }
}

当智能感知被拉起以访问以下属性之一时，没有指示可以对其进行写入，读取或同时读取和读取：

在此处输入图片说明

同样，在查看文档时，我们也不太确定：

在此处输入图片说明

这样，我们添加了gets或sets，gets或sets，以使程序员在编写代码时更加容易。当然，不会写大量的代码来读取和处理某些数据，而只是发现您无法按预期将这些数据写回属性。

在此处输入图片说明

— 麦克风
source

感谢您的彻底回答。我认为这些是Visual Studio IDE的限制。我已经考虑过了，我认为智能感知可以向您显示哪些属性，例如，get仅在当前上下文中。弯曲文档以适合特定的开发环境不是很方便。我仍然认为Visual Studio和C＃紧密相关，以至于这可能是正确的解决方案。

— 托马斯

1

@Tomas我同意Visual Studio应该有更多区别。当我不正确地使用该属性时，很高兴能给我一条红色的波浪线。

— Mike

2

StyleCop使用由Gets or Sets ...规则SA1623强制执行的符号。

链接页面列出了您尚未列出的另一种情况：

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
    get { return this.enabled; }
}

您列出的另一个选项是。

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; set; }

与

/// <summary>
/// ID that uniquely identifies this <see cref="User" /> instance.
/// </summary>
public int ID { get; }

这不会提供该属性是只读的智能感知提示信息，你能想出这种情况下的约定过，但是Gets ...，Gets or Sets...做这项工作很好海事组织。

在StyleCop规则上还列出了其他变体，使用可以清楚地看到它们，Gets or Sets...但可能并非没有。

同样，当从Doxygen或Sandcastle之类的文档生成文档时，完整的符号会更好地记录API（例如）。

— 尼古拉·但丁
source

2

我唯一一次在XML注释中添加有关获取和设置属性的信息是当它的行为不符合预期时（直接公共获取和设置）。

如果其中一个是私有的，或者它们包含其他逻辑，那么我会提及它们，否则，我只记录该属性的意图。

— 卡兰德里
source

1

我会更详细一些。

另一个就像在增加一个计数器变量之后，注释“增加计数器”。

显然有一个Get and Set。如果您有一个私有的二传手，那将很明显，因为您将拥有private关键字。

注释应该增加价值，而不仅仅是代码实际的注释版本。

— zz
source