Documentation 我应该记录我的私有方法吗？_Documentation_Private Members

Documentation 我应该记录我的私有方法吗？

documentation

Documentation 我应该记录我的私有方法吗？,documentation,private-members,Documentation,Private Members,私有方法文档只能由有权访问源代码的人查看。它值得为此付出努力吗？就我个人而言，我觉得它是值得的。文档通常对维护软件的未来开发人员最有用，尤其是成员文档即使是公共API文档，对除开发人员以外的任何受众的使用也是有限的。为以下人员编制文档-他们会感谢您。我不会。如果您的私有方法需要文档，那么在这方面花些时间使代码更干净可能是值得的编辑：即使有摘要，我也不会记录。私有方法可以改变、重新萌芽、消失。OO的基本原则之一是封装。您不需要知道私有方法在做什么。至于开发人员，谁来更新所有这些文档？你第一次但

私有方法文档只能由有权访问源代码的人查看。它值得为此付出努力吗？

就我个人而言，我觉得它是值得的。文档通常对维护软件的未来开发人员最有用，尤其是成员文档

即使是公共API文档，对除开发人员以外的任何受众的使用也是有限的。为以下人员编制文档-他们会感谢您。

我不会。如果您的私有方法需要文档，那么在这方面花些时间使代码更干净可能是值得的

编辑：即使有摘要，我也不会记录。私有方法可以改变、重新萌芽、消失。OO的基本原则之一是封装。您不需要知道私有方法在做什么。至于开发人员，谁来更新所有这些文档？你第一次但是以后呢

编辑2：来自评论

我强烈反对。私有方法唯一不应该被记录的时候（在某种程度上）是当它的目的从它的名字和源代码中是完全明显的时候。如果你的代码有什么“聪明”的地方，那就值得一提，解释你为什么这样做

我非常同意，但是。。代码不应该是“聪明的”，代码应该是功能性的和可读的。大多数情况下，您应该使代码对读者尽可能透明，如果您需要对其进行注释，那么您应该在点击javadoc（或您使用的任何东西）之前让代码更清晰

编辑3：

你更愿意看什么

/**
*   This method doesn't do what you expect it to.
*   Below you will find a whole ream of impenetrable
*   code. Where there are bits that look that they do x, they don't
*   they do y. 
**/
private void someComplexInternalMethod()
{
     ...
     badly named variables
     comments to describe intent
     perhaps some out of date orphaned comments
     as code has been removed but comment remains

     ....
     ....
     looong methods 
}

private void WellNamedMethod()
{
     ...
     well named variables
     shorter method, highly cohesive
     self documenting
}

确实如此。在除了普通软件以外的任何软件中，通过正确使用注释，您都可以更快地理解代码，即使是几个月后的原始作者也是如此。

是的，当然。六个月后你可能需要回来做一些维护。几句恰当的评论可以为你节省大量的时间和精力。您可能不需要像使用公共API那样对其进行文档记录，但一些注释不会有什么坏处。

当您在6个月后访问您的私有方法时，它们是否会像现在这样对您有意义？您是否需要花费数小时来跟踪组件之间的关系

根据我的经验，良好的文档记录绝不是浪费时间。

是的，有必要记录您的私有方法。随着越来越多的开发人员使用您的代码并修改您的代码，这变得越来越必要。私有方法与公共方法一样保证特定的功能。区别在于代码的使用方式。私有方法的文档化加速了重构过程。

好吧，这些代码也应该是可维护的，你不认为吗？当然，它们应该被记录下来！您必须在几个月后查看该代码，并且在进行更改时需要参考一些内容。

是的，是的，是的。记录您编写的任何代码

最终会有人维护您编写的代码。文档是一种帮助他们进入您在编写特定代码时的思维方式的方法。私有函数对于文档来说尤其重要，因为它们在代码中的使用量往往最少，开发人员可以从中推断出它们的不变量

记录公共方法对于维护人员和使用您的包的人员都很有用

记录私有方法对维护人员或包（包括您）很有用

简言之，它的必要性略有不同。例如，记录私有方法不需要正式。

为了清晰起见，您应该重构代码，这样就不需要实现文档

首先，不要使用注释代码的能力来让您懒于编写明显的代码

用不同语言表述代码所述内容的文档是多余的。和冗余代码一样，这种冗余也必须保持，但通常不是。如果您的方法名称没有立即表明其用途，那么它们就没有很好的名称。在命名良好的类和方法上依赖文档将不可避免地对您产生不利影响。所需要的只是一些人忘记更新文档的例子，最终你会陷入可怕的混乱。例如：

坏的

private void Update(string sValue, DateTime dValue)
{...}

更好

private void UpdateEmployeeInformation(string jobTitle, DateTime hireDate)
{...}

第二个版本需要记录吗？名称标识了它的用途，参数名称使它清楚地显示了预期要传递的内容

如果您的方法太长、太复杂，需要一个新的解释，那么您需要将它们分解为逻辑功能位，这些功能位可以很好地命名并高度集中。IMHO，这比一些写得很糟糕的内联文档要容易理解得多，这些文档可能是最新的，也可能不是最新的——我仍然要通读所有的代码，以确保它符合文档所说的应该做的，在大多数情况下，我会假设文档没有得到维护，并忽略它

您还应该进行单元测试，以调整代码并使功能更加明显。对于命名良好的类、方法和单元测试，附加文档的作用是什么？

任何做得足够复杂、既有趣又不明显的方法都值得花时间通过一些文档来澄清。

是的。正如我听到的这个笑话：

编程就像性一样。一个错误，你必须支持它到你的余生

当然。编写代码时，始终假定两年后需要您修改代码。方法总结是最重要的。我无法告诉你有多少次我发现了bug，因为我在写文档（摘要、参数、返回）时意识到我遗漏了什么。