记录文件，类和构造函数的正确方法是什么？

Question

一致地为构造函数和类和仅包含单个类的文件编写注释块的最有用/最标准/最不令人惊讶的方法是什么？

• 类的注释块，而不是构造函数
• 构造函数的注释块，而不是类
• 构造函数和类的注释块 - ＆gt;在那种情况下，每种细节应该包含哪些细节？

然后文件本身？如果它只包含一个类，是否需要注释块？应该去哪些细节？

我想尽量避免在类，构造函数和文件注释块之间重复。

Answer 1

Answer 2

就个人而言，我只在构造函数中注释是否有特别的东西可以评论它（比如特殊的初始化）。

我不会说这是“最有用”的方式，但它保持代码整洁，并且重复两次相同的事情并不是真的需要（如果这是您的关注）。

Answer 3

评论所有内容 - 文件（作者，版权，描述等），类（描述，代码示例），方法和属性。 Here是phpDoc条评论的好例子。

Answer 4

我个人认为类和方法文档是最重要的文档。当我编写代码时，当代码完成向我显示属于方法的文档时，我需要IDE的帮助。这样我就可以轻松找到我需要的方法。

由于我尝试将类的显式初始化保持在最低限度，因此我不会使用构造函数注释。因此，我尽量避免使用构造函数。

方法或函数中的代码应尽可能清晰，方法是使用声明性变量名称并尽可能地保持它们的小。只有当我做出意想不到的事情时，例如我才会对集成问题进行评论。