记录文件,类和构造函数的正确方法是什么?
|
为构造器和仅包含一个类的类和文件一致地编写注释块的最有用/最标准/最令人惊讶的方法是什么?
类的注释块,而不是构造函数
构造函数而不是类的注释块
构造函数和类的注释块->在这种情况下,每种注释中应包含哪些详细信息?
然后文件本身?如果仅包含一个类,是否需要注释块?什么细节应该去那里?
我想尽量避免在类,构造函数和文件注释块之间重复。
没有找到相关结果
已邀请:
4 个回复
念炯
标记也是可选的,因为您可能能够为项目自动生成它。而且,如果我没记错的话,PHPDoc甚至可以为没有标签的所有内容设置默认软件包。 对于一般的文档,让我从一个示例开始(最后是一个更长的示例): 您可以解释多少次“ uri”是什么意思: 请注意,对于
,它解释了URI的含义(只是在我假设的注释中有话要说),而it3ѭ中则没有,因为在那里您至少可以说“ abs表示绝对”。两次。 如果您不是开源项目(或需要交付COMPLETE !!! 11eleven api文档): 我强烈建议使用适当的,较长的和描述性的类,变量和方法名称代替文档。 在doc块中再写一些东西是没有好处的,因为它是2011年,并且我们有120个字符宽的终端和自动补全功能,因此不再需要为了节省一些字符而缩写所有内容。 我什至会争辩说,记录琐碎的事情会迫使您浪费时间在那些没有价值的事情上,这对您和您的团队都是有害的,因为您养成了总是编写琐碎的文档而不再阅读它们的习惯。 一个好的注释应该说明为什么要做某件事,而代码本身应该说明如何做而无需进一步的注释。 我最喜欢的冗余文档示例是以下示例:
一些准则说您必须记录所有内容,最终您会被人们一次又一次地陈述显而易见的内容。 这没有任何价值,但是在读取代码时浪费了时间。 正确命名的示例:
这段代码很容易记录,因为您需要解释\“ kg \”的含义,因为某些人可能会使用其他系统,而您无法通过Google搜索\“ kg \”。 我赞成写作
doc块是多余的,因为真的可以期望在
上调用
来设置人的权重。无需再次写出来。 使用$ kilogramm作为参数还可以避免您在文档中对其进行解释的麻烦,我会说,根据您的环境,如果每个人确实不知道Google的“公斤”,都可以用它来搜索“公斤”测量单位。 @PHPDoc文档 我所有的拙见当然 如果您不使用类型提示,请始终使用@param标记。 始终使用@return标签 根本不要使用@author标记。收集代码的所有权更有价值,并且无论如何信息都在源代码控制存储库中。 如有必要,仅使用@copyright标记。我只喜欢拥有许可文件,但我不是律师,因此可能有必要。 内联评论:
如果这些是单独的“块”,则将其移至描述性的命名函数
其他资源: 我在一些会议上针对该主题的演示文稿的幻灯片:
以及其他小一点,大一点的:rant12ѭ 书籍参考:
重构:改进现有代码的设计 一个更长的例子
让我们逐行查看该文档告诉您的内容。 (我在这里开玩笑是为了让我明白我的意思)
那么在xyzRequest上调用-> initialize会初始化该请求吗?真?好吧,如果您这么说!
我们被告知第三个参数的选项,而不是第二个或第三个参数的选项,但是如果我们知道框架,也许我们知道那些选项? (由于我们无法弄清楚-> initialize在没有人告诉使用的情况下会做什么,所以我们可能不那么聪明...)
是的,这里有类型提示。因此,如果该方法需要一个“ xyzEventDispatcher实例”,我们需要传入一个“ xyzEventDispatcher实例”。很高兴知道。
好。因此它不是线性数组。但是我需要将“初始化参数”传递给本可以弄清楚的“初始化”方法。 仍然不知道我实际上需要传递的内容,但是只要记录在案就可以了!
因此,布尔值的返回值为\“ true \”(对于\“ good \”)和\“ false \”(对于Bad \“)。
因此,如果在执行函数命名时发生错误,则会引发异常? 因此,异常用于错误情况。好。很高兴知道。 不会告诉我return false和异常之间的区别。 @throws自身很好,因为它可以添加信息 顺便说一句:为什么这个大胆而不是一个@link
荆怖赡
耐钨徒
邵酮