Question

最近，我的项目经理要求为我们迄今为止所做的所有工作撰写评论，摘要和#regions。甚至他也要求为变量声明写作。就像我们宣布金额为双倍一样，他要求我们写这样的

  /// <summary>
    /// RegularPay declared as double
    /// </summary>
    private double m_dRegularPay;

即使是Get Set

也是如此

  /// <summary>
    /// Get and Set FirstName
    /// </summary>
    public string FirstName
    {
        get
        {
            return m_sFirstName;
        }
        set
        {
            m_sFirstName = value;
        }
    }

实施一些代码时的区域

   #region EmpHourly
    /// <summary>
    /// Get Employe Hourly Amount
    /// </summary>
    /// <param name="EmpAmount"></param>
    /// <param name="EmpRegularHours"></param>
    /// <param name="EmpHourlyRate"></param>
    /// <param name="EmpBonusPay"></param>
    /// <param name="EmpOtherHours"></param>
    /// <param name="EmpOverTimeHours"></param>
    /// <returns></returns>
    public bool GetEmpHourlyAmount(out double EmpAmount, out double EmpRegularHours, out double EmpHourlyRate, out double EmpBonusPay, out int EmpOtherHours, out int EmpOverTimeHours)
    {
     }

我想知道的是更好的编码标准方法

Answer 1

评论类字段和属性是一种很好的做法，但这里的区域似乎毫无意义。我还要补充一点，过度使用out变量并不是很好的C＃风格。返回一个物体会更好。

Answer 2

地区太可怕了。他们只是隐藏您想要查看的代码。对我来说，就像试图读一本书一样，但是有人对每一段都进行了封面。这毫无意义。

我也认为学校评论请求值得推迟。它增加零值，创建繁忙工作，并模糊真实的注释（代码本身）。

/// <summary>
/// RegularPay declared as double
/// </summary>
private double m_dRegularPay;

这说了三次同样的事情。它在评论中说，RegularPay是一个双精度，私人双重RegularPay是一个私人双重，而m_dRegular支付是一个私有双。

实际上，评论和符号表明在某个时间点 m_dRegularPay是双倍的。私有双标识符声明它仍然是私有双。

private double regularPay;

只表示一次。

Answer 3

这个评论惯例似乎过于热心......但不一致。

使用注释“RegularPay声明为double”来注释行double RegularPay是一项愚蠢的工作。这是显而易见的，指出它是多余的，浪费时间。

在您所在的地区，GetEmpHourlyAmount的摘要可能很重要，但不会将其视为此类。该方法的名称与评论一样有用。

一般来说，如果您发表评论，评论应该告诉您名称显然没有告诉您的内容。评论应该显示更多有用的信息。

Answer 4

IMO区域是一种代码气味。它们会影响{{1}}以及readability。当拥有大型代码文件并需要划分代码时，您需要区域。但是，你应该真正写小班，每个班都做自己的任务。

在编辑带有区域的代码文件时，确定要将新方法放在哪个区域是很痛苦的。我经常看到许多区域包含应该属于另一个区域的代码。

评论属性很好但你也应该写出属性的用途\使事情更清楚。从名称本身来看，理想的目的应该是显而易见的。

我认为写''字段被声明为double'这样的评论是没有意义的。 IDE intellisence已经完成了使评论多余的工作。

另外，请考虑使用auto properties删除样板代码。

Answer 5

对我来说似乎有点大概。

为了记录它们而记录自描述方法/变量是浪费金钱。它们变得陈旧，过时并使代码更难阅读。

此外 - 使用区域是代码气味的标志。如果你有一个如此庞大的课程，你必须将它分解成区域，你需要重新考虑设计。

文档和区域不会修复错误代码，并且难以维护。好的代码是自我描述的，不应该像“评论一切”那样需要一揽子规则。

在适当的情况下进行评论，并使用区域作为警告标志，您需要修复文件的结构。

Answer 6

我认为使用区域的更好方法是在函数很大的情况下对函数和函数部分进行逻辑分组。对于功能描述总结就足够了，我想。

Answer 7

表示痛苦明显的评论比没有评论更糟糕。除了在代码中添加噪声之外，它们还倾向于与它们描述的代码不同步，并且最终会对代码所做的事情表示不满。

如果确实必须有评论，而不是“获取和设置FirstName”，我可能会将评论更改为“获取或设置员工的名字”。

而不是“RegularPay计算为双倍”，而不是......嗯......变量的更好名称。 VS使重命名变量变得如此容易，并且很容易将鼠标悬停在变量上并查看它是什么，最好的文档就是代码本身的更具描述性的形式。

至于#region，如果该区域将包含多个方法，那么明确命名的区域可能有所帮助。但是对于单一方法，它不值得付出努力 - VS可以随时折叠方法，因此#region会增加噪音并且不会为你带来任何收获。

Answer 8

这些注释可用于自动生成代码文档。请咨询您的项目经理是否是这种情况。

我同意其他人的意见，即评论显而易见的事情绝对是浪费时间。定期支付是双倍的是一个这样的评论。一个示例或其他不明显的信息会更有用。例如，“每周定期付款”或“每年定期付款”或“以美分定期付款”。这些评论是必要的，因为正确思想中没有人会将变量命名为RegularPayPerWeekInCentsExcludingOvertimeRatesAndTaxDeductions。

Answer 9

正如您所做的那样，对变量进行注释没有任何意义，因为它隐含地显示了这一点有效性。

   private double m_dRegularPay;

全部说明

现在对于地区来说，最好的地方是你有一个巨大的代码库，你可以逻辑地让占位符说像处理程序，构造函数，计算等... 对于一个新进入者来说，它是一本书的索引（有时可能非常有帮助）

Answer 10

如果在类/文件区域中有几千行代码可能会有帮助

Answer 11

区域应该永远不会在函数内部使用或只包含一个函数 - 简单的注释或块就足够了。如果你的功能看起来太大，你应该考虑重构。如果您的类实现了多个接口，那么区域可以在接口实现周围有意义。

一个类应该永远不会只包含一个区域 - 否则该区域只是一个类（可能你已经在类上有一个注释或块），所以这只是复制信息。

在您的私有变量声明周围放置一个区域 - 这取决于您的编程风格，我将所有私有声明放在类的顶部，99％的时间打开文件我正在修改函数或属性因此，除非我正在创造一些新的东西，否则不需要看到它们，对我来说，将它们放在一个区域是有意义的。

Theres可能还有一些可能这个列表会随着时间的推移而增长。我并不是说以这种方式使用它们，但如果您打算使用它们，请更多地使用它们并明智地使用它们。

在我们正在实现的每个方法中使用#region是否合适

11 个答案: