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

Question

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

因此,已经StyleCop的这一规定为summary,param和return文档标签.

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

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

例如(也许我试图说明不好的评论):

//if exception quit

与

// 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

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

不过，总的来说，强迫自己写出完整、正确的句子也会迫使你更多地思考你在评论中真正想表达的内容。我经常发现自己在重新思考我真正想在评论中包含什么内容，将其完整写下来。

没有充分的理由为了简洁而牺牲清晰度。将来需要有人理解代码。这些评论是为他们准备的，所以要让他们更容易理解。