为什么注释块很重要？

曾经有人说过，我们应该在所有方法的前面加上 /// <summary>注释块（C＃），但没有解释原因。

我开始使用它们，发现它们使我非常恼火，因此停止使用它们，除了库和静态方法。它们体积庞大，我总是忘记更新它们。

是否有充分的理由/// <summary>在代码中使用注释块？

我通常//一直在使用注释，这只是/// <summary>我想知道的内容。

尽可能使用它们。

是的，这些特殊注释已成为该方法的文档。<summary>当您或其他人准备调用您的方法时，生成的，参数标签等内容将以智能感知的形式显示。他们基本上可以查看您的方法或类的所有文档，而不必转到文件本身来确定其作用（或者尝试仅读取方法签名并希望获得最佳效果）。

是的，绝对将它们用于您想要保留的任何东西，或者可以共享。

另外，将它们与Sandcastle和Sandcastle帮助文件生成器结合使用，后者将XML输出转换成漂亮的MSDN样式的文档。

我工作的最后一个地方，我们每晚都重建文档，并将其作为内部主页托管。公司的名字缩写是MF，所以它是MFDN;）

通常，尽管我只是生成一个.chm文件，但该文件很容易共享。

当您开始以MSDN格式看到所有内容时，您会沉迷于记录所有内容，您会感到惊讶！

如果您的编码标准要求您使用此类注释（并且API或框架的编码标准可能会要求），那么您别无选择，则必须使用此类注释。

否则，请认真考虑不要使用此类注释。在大多数情况下，您可以通过更改代码来避免此类情况：

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

至

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

至

    public bool IsAuthorizedToAccessResource( User user ) {

    }

您的类，方法和属性的命名应该是不言而喻的，因此，如果您需要这些，那可能是一种气味。

但是，我建议您在API，库等中的任何公共类，方法和属性上使用它们。至少，它们会生成文档来帮助任何开发人员使用您的文档，并且会阻止您写他们。

但是无论如何，您都要对其进行切片，维护或删除它们。

如果您发现必须继续前进并编辑注释以与新代码相对应，那么您可能一开始就把它们弄错了。summary元素应确切地包含-摘要-您要概括的内容的内容和原因。

描述如何东西在评论作品违反了DRY。如果您的代码不够自我描述，那么也许您应该返回并进行重构。

是的，我已经创建了它们。[从头开始构建新系统时]

不，我从未从中受益。[在需要维护的现有系统上工作时]

我发现“摘要”注释最终趋向于与代码不同步。而且，一旦我注意到一些行为不佳的评论，我就会对该项目的所有评论失去信心-您永远不确定要信任哪些评论。

忘记做某事并不意味着一个坏主意。忘记更新任何文档了。我发现这些在我的编程中非常有用，并且继承我代码的人们很高兴拥有它们。

这是记录代码的最明显的方法之一。

不得不查找源代码以阅读内联文档或挖掘涉及代码功能的文档是一件很痛苦的事情。如果您可以通过智力弹出一些有用的东西，那么人们就会爱上您。

“ 必须像我一样非常使用它；） ”

我曾经玩过注释（///）。对于课程，您可以像这样简单地发表评论

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

但是，对于一种方法，您可以附加更多内容，并提供参数和返回类型的描述。

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

您可以使用快捷方式创建此注释(///+Tab)。

使用它们，除了库

那是他们有用的时间。启用XML文档生成功能，并在没有其项目的情况下引用该程序集，将在intellisense中显示更多详细信息。

但是对于当前项目的内部而言，它们只是妨碍了工作。

我使用它们，但是正如其他一些人所说的那样。对于较小的方法，它们可以轻松地大于所解释的代码。它们对于生成可以提供给系统新手的文档非常有用，以便他们在学习系统时可以参考一些内容。即使作为程序员，我们通常可以找出一些代码是什么，因为有注释来指导我们并充当拐杖是很好的。如果必须将其写下来，则代码中最有可能保持更新的位置（比某些Word文档更容易更新）。

我在VB中使用了等效项（因为它们不允许我使用C＃-显然太难了……无可奉告。）我发现它们非常方便。在大多数情况下，我只是等到过程或功能完全完成后才放入它们，只是为了避免更改注释或使它们“不同步”。

我不一定要写小说-只是基础知识，参数描述和一些说明（通常是在其中出现“与众不同”的情况时），我宁愿不要在其中找到解决方法或其他废话（“暂时”是没有选择的。）（是的，我知道，“暂时”可以持续数年。）

我对未注释的代码感到非常恼火。一名顾问写了我们组件之一的初始版本，没有发表任何评论，他的名字选择到处都是。他已经离开了一年，我们仍在整理他的东西（除了处理我们自己的东西。）