.net注释应以大写字母开始并以句点结束？

问题描述：

根据我得到的反馈，我可能会与同事提出这个“标准”。这可能会成为一个自定义StyleCop规则。有没有写过？.net注释应以大写字母开始并以句点结束？

因此，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); 
}

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

请备份您的意见。你有评论的艺术的一个很好的参考，特别是如果它涉及。净？

谢谢。

就我个人而言，我会把这些类型的评论放在代码块里面，如果你可以对else条件有一个评论（如果存在的话）。 – 2010-05-25 23:38:21

答

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

// SERVER

因为IDE colorizes意见，这使得它在方便的时候有这样简短的话来堵精神上的东西帮助成段。我通常只做十几行代码。如果时间更长，那么#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>

那些我觉得更容易被别人阅读和它有助于有冗长和干净的格式。

+1对于摘要位，这非常好。我的一些同事设置Resharper去除所有“传统”评论。 – 2010-05-25 23:53:24

您在代码中输入ºs？ – igul222 2010-05-25 23:57:50

当然！这只是alt + 176。我在工作中处理这个符号很多！ :) – JYelton 2010-05-26 00:18:23

答

花时间写出清晰，可读，可理解的评论永远不会浪费。我有多少次在稍后的日子重新阅读我自己的评论，以致于很难理解它们。潦草写作或严格格式化评论的人通常会在其代码中使用相同的特征。

答

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

应避免在您的示例中出现琐碎的注释。他们除了噪音之外什么都不加

对于避免无关紧要的评论的提示+1 – 2010-05-26 11:09:43

答

如果你在Visual Studio中评论方法，你应该考虑在方法的顶部使用summary和params。这样你就可以在代码完成时获得有关该方法的详细信息下面是一个例子

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

引用OP“所以，Stylecop已经规定了这个摘要，参数和返回文档标签”... – spender 2010-05-25 23:52:29

答

我发现，当我尽量简短带注释（即不完整的句子，片段），我经常离开了关键假设或词实际上澄清意义。我现在很难提出一个具体的例子，对不起。

尽管如此，强迫自己编写完整，适当的句子也迫使你更多地思考你真正想要评论的内容。我经常发现自己重新思考我真正想要写入评论的内容。

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

.net注释应以大写字母开始并以句点结束？

相关推荐