我是一名PHP Web开发人员，他正在寻找一种经过验证的方法来编写好的文档（也称为docblock）。
有几种文档样式，例如：
/** * Element name: class, function, variable etc. (Optional) * * Short description. * * Long description. */
/** * Function name * * @param $foo * @return bar */
/** ********************** * NAME: Func_Name * DESC: Does A Lot * RETurn: number * NOTES: foo bar foo... ********************** */
但我应采用哪种文档样式？
我假设不同的文档样式应该用于不同的语言元素：
功能也许应该使用＃2方法，
而一个班级应该使用＃1方法。
内联代码可以这种方式记录（＃5）：
// short description // of // what the following code does.
我知道phpDocumentor，但不喜欢学习如何使用它的想法 学习如何使用像phpDocumentor这样的东西似乎很荒谬，所以我可以记录我的代码 （虽然我很欣赏任何开源项目，包括phpDocumentor）
答案 0 :(得分：1)
其他人可能会告诉你更多关于PHP的具体内容。
但是，我认为最重要的是要弄清楚“谁将会阅读这个以及何时阅读”。如果您正在编写一些您期望很多人使用和阅读的主要API，您需要提供完整的规范。一个很好的正式风格，清楚地显示参数是什么，返回值是什么等，几乎是强制性的。
如果您不是在编写世界级API而是编写内部代码，请考虑您的读者。大多数读过这篇文章的人都会仔细阅读代码。他们将实例化一个类或调用一种方法来完成某些事情，他们不会关心他们可能自己想出的所有事情。在浏览时你只会得到一两次关注，你必须充分利用它。
在这些情况下，完整的描述，完整的参数列表等都将成为“视觉噪音”。如果你真的写了令人惊讶或独特或重要的东西，它可能会错过。所以你最好选择记录什么是独特的，而不是记录。然后，文档的存在将向您的读者表明他们实际上想要阅读，而不是注意他们期望的事情。
除此之外，我认为你应该总是仔细设计你的课程，特别是你的功能，这样就没有人需要阅读文档了。如果有人需要阅读“简短描述”来了解你的功能是什么或者需要什么，那么你在命名它或将它与其他功能区分开来时做得很糟糕。文档应该是最后的手段，用于传达在签名中无法表现出来的东西。