it-swarm.cn

为什么注释块很重要?

曾经有人说过,我们应该在所有方法前加上/// <summary>注释块(C#),但未解释原因。

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

有没有充分的理由使用/// <summary>您代码中的注释块?

我通常使用//一直评论,只是/// <summary>我想知道的块。

49
Rachel

尽可能多地使用它们。

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

91
Ryan Hayes

是的,绝对将它们用于您想要保留或共享的任何内容。

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

我上次工作的地方是每晚我们重新生成文档,并将其作为内部主页托管。公司的名字缩写是MF,所以它是MFDN;)

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

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

17
Tom Morgan

如果您的编码标准要求您使用此类注释(并且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 ) {

    }
12
azheglov

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

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

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

4
John MacIntyre

如果您发现您必须继续前进并编辑注释以与新代码相对应,那么您可能一开始就把它们弄错了。 summary元素应完全包含-摘要-您要汇总的内容的whatwhy

描述how注释中的某些内容违反了DRY。如果您的代码不够自我描述,那么也许您应该返回并进行重构。

2
Nobody

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

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

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

1
Preets

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

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

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

1
Abe Miessler

必须像我一样非常使用;)

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

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)

1
Sreekumar P

我在VB(因为他们不允许我使用C#-显然太难了...没有评论。)。)。)中,我发现它们非常方便。大多数情况下,我一直等到如果只是为了避免更改注释或使它们“不同步”,则在将它们放入之前,过程或功能几乎已完成。

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

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

0
MetalMikester

使用它们,除了库

那是他们有用的时间。启用XML文档生成功能,并且对没有其项目的Assembly的引用将在intellisense中显示更多细节。

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

0
Richard

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

0
Todd Williamson