Warning: file_get_contents(/data/phpspider/zhask/data//catemap/0/windows/15.json): failed to open stream: No such file or directory in /data/phpspider/zhask/libs/function.php on line 167

Warning: Invalid argument supplied for foreach() in /data/phpspider/zhask/libs/tag.function.php on line 1116

Notice: Undefined index: in /data/phpspider/zhask/libs/function.php on line 180

Warning: array_chunk() expects parameter 1 to be array, null given in /data/phpspider/zhask/libs/function.php on line 181
Documentation 我应该记录我的私有方法吗?_Documentation_Private Members - Fatal编程技术网

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,因为我在写文档(摘要、参数、返回)时意识到我遗漏了什么。

<