什么是文件,类和构造函数的正确方法?
什么是始终如一地写只包含一个类的构造函数和类文件注释块最有用的/最标准/最令人惊讶的方式?什么是文件,类和构造函数的正确方法?
- 注释块类,而不是构造
- 注释块构造函数,而不是类
- 注释块都构造函数和类 - >在这种情况下,应该在每个走什么样的细节?
然后文件本身?如果它只包含一个类,它是否需要注释块?应该去哪些细节?
我想尝试尽可能地避免类,构造函数和文件注释块之间的重复。
-1 ZF提供的文档数量对于公共框架是可行的,但不一定适用于所有应用程序。我也会争辩说,ctor和getter和setter的简短描述是完全多余的。 – Gordon 2011-04-21 09:24:19
如果你想重用你的代码(或者别人会这么做) - 像Zend那样记录它。 5分钟现在将为您节省大量时间 – biakaveron 2011-04-21 09:29:17
@biakaveron您是否打算说,特别是关于构造函数,设置函数和getter的简短描述可以更轻松地重用代码?如果是这样,为什么? – 2011-04-21 09:37:49
就个人而言,我只在构造函数,如果有什么特殊的地方发表意见(如特殊的初始化)发表评论。
我不会说这是“最有用”的方式,但它保持代码整洁,重复两次相同的事情并不是真的需要(如果这是你的关注)。
我个人认为的类和方法的文档是身边最重要的文档。当我编写代码时,当代码完成向我显示属于某个方法的文档时,我需要IDE的帮助。这样我就可以轻松找到我需要的方法。
由于我试着类的显式初始化到最低限度,我就不用户构造意见。因此,我尽量避免使用构造函数本身。
方法或函数中的代码应尽可能清晰,方法是使用声明式变量名称并尽可能小。只有当我做出意想不到的事情时,我才会对它们进行评论。
*(相关)* [什么是在PHP5评论的有效和可读的方法](http://*.com/questions/5618592/what-are-the-valid-readable-approaches-to-commenting-in-php5/5618786) – Gordon 2011-04-21 09:55:06
句法“正确的方式”是由生成的结尾用户文档在工具完成解析之后即可看到。这在很大程度上是实现定义的文档内容的质量由用户在使用之前是否仍然需要阅读源代码来定义。 - 也是IDE自动完成友好的文档语法的奖励点。 – 2016-10-06 02:22:21