Question

根据我得到的反馈，我可能会与同事一起提出这个“标准”。这可能会成为自定义StyleCop规则。有没有写过？

因此，Stylecop已经为summary，param和return文档标记指定了这一点。

您是否认为从评论中要求相同的内容是有意义的？

相关说明：如果评论已经很长，那么它应该写成正确的句子吗？

例如（也许我太努力去说明不好的评论）：

//if exception quit

VS

// If an exception occurred, then quit.

如果想的话 - 大部分时间，如果一个人不愿写评论，那么它也可能是提供信息的。考虑这两个样本：

//if exception quit
if (exc != null)
{
    Application.Exit(-1);
}

和

// If an exception occurred, then quit.
if (exc != null)
{
    Application.Exit(-1);
}

可以说，一个人根本不需要评论，但是由于提供了一个，我认为第二个更好。

请备份你的意见。您是否对评论艺术有很好的参考，特别是如果它与.Net有关？

感谢。

Answer 1

如果代码需要评论，那么它应该很好地形成，因为IMO可能存在需要解释的（非平凡的）概念。

应避免使用例如示例中的琐碎评论。他们除了噪音之外什么都没有。

Answer 2

我经常写评论只是为了帮助我找到代码段。（我也使用区域。）例如：

// SERVER

因为IDE会为评论添加颜色，所以有时会使用这样的简短评论来帮助精神上阻止某些内容。我通常只为十几行代码执行此操作。如果它更长，那么#region似乎更好。

我也常常在评论中写下笔记，有时作为我自己的参考：

// NOTE: -273.15 is absolute zero in °C, used for a MinValue below

这不是一个语法上美丽或完整的句子，但它是有道理的。

我倾向于使用更完整的结构化句子在我的方法摘要中，如下所示：

/// <summary>
/// Populates the properties of a Sensor object based on
/// the XML components of its data file.
/// </summary>

我认为更有可能被其他人阅读，并且有助于获得冗长和清晰的格式。

Answer 3

我发现当我试图简短地评论（即不完整的句子，片段）时，我经常会忽略实际上澄清含义的关键假设或词语。对不起，我现在很难想出一个具体的例子。

一般而言，强迫自己写出完整，恰当的句子也会迫使你更多地考虑你真正试图用评论说的话。我经常发现自己正在全力以赴地重新思考我真正想要包含在评论中的内容。

没有充分的理由在简洁的祭坛上牺牲清晰度。有人将来需要了解代码。评论是针对他们的，所以让他们很容易理解。

Answer 4

花时间写清楚，可读，易懂的评论永远不会浪费。有多少次我在以后重新阅读我自己的评论只是为了努力理解它们。撰写草率或格式错误的评论的人经常会在他们的代码中使用相同的特征。

Answer 5

如果您在visual studio中评论方法，则应考虑使用方法顶部的摘要和参数。这样，您就可以在代码完成期间详细了解该方法。这是一个例子

    /// <summary>
    /// you summary here
    /// </summary>
    /// <param name="param1">Describe parameter usage</param>
    /// <param name="param2">Describe parameter usage</param>

.net评论应该以大写字母开头并以句点结束吗？

5 个答案: