phpdoc注释规范 - 总结 ¶
作者：KK
发表日期：2016.9.17
以上介绍了各种备注怎么写之后，我总结一下普通开发中应该有怎样的注释:
一个类要有介绍说明这个类是干什么的，类的作者是谁
要说明类的常量和各个属性表达了什么含义
要说明类的方法的作用
要说明方法的作者，并且谁最后修改这个方法的最好就把作者换成修改者的，方便有问题时快速找人（可能很少人能做到每个方法都写作者，但如果能做到，那类的作者就没什么必要存在了，只要方法代码能找到编写的人就可以，或通过代码仓库记录去找）
如果方法或属性的使用需要注意怎么用的，要在详细介绍里添加示例代码
方法有参数的话要@param，要注明参数的类型与含义
方法有返回的话要@return，至少要注明返回类型，必要时加上返回值说明
以上是我觉得对项目维护来说算是比较实用的注释了，而phpdoc里还有@category、@link什么的这些其实对咱们平时接触的公司项目没啥用处，除非咱们的代码要开源出去，做得规范点，可以说这些是“面子工程”下要做的表面功夫而已（个人浅见）
目前的现状 ¶
大部分写得不规范
在咱们的行业里当然是菜鸟居多的了，他们大部分不知道如何写好注释，于是风格都是很自由，有的也见过phpdoc这样的注释，但他们没有系统地学习过这种注释
于是在半懂半不懂的情况下写得似是而非，最终严格地说他们写出来的可能无法被生成器生成文档，比如这样介绍一个参数但没有注释参数的类型：
/** * 方法的介绍 * @param $userId 用户ID */其实应该是
/** * 方法的介绍 * @param int $userId 用户ID */所以如果要写出能被生成文档的phpdoc注释还是要专门学一下的
没有多少团队会生成文档
其实用类似apigen这样的程序生成API文档的项目团队有多少呢？恐怕没多少
于是，是否需要写规范的phpdoc注释就已经变得不痛不痒
广大开发者对API文档没啥需求
如果你测试一下将TP框架的代码生成文档，就会在左侧目录树看到很多命名空间结构和类嘛，点击就看具体的
可是实际上就连我自己本人要学习一个类怎么用的话，都很少去看这些文档，更别说团队的其他成员了
比如一个新员工加入了公司吧，他要上手公司的代码，你以为他看这个API文档能快速上手公司的项目开发吗？不可以
所以这种情况下，API文档存在与否其实变得无关痛痒
API文档的存在意义在于速查
以我个人的开发经验来说，假如我忘记了
app\games\某某Game的某个方法的用法或者参数说明时我会通过浏览器收藏夹快速打开项目的API文档并在左侧栏目录快速跳转到这个类的说明文档里找到相关的方法注释去看
由于API文档总算是视觉效果比代码效果好的，所以它的呈现效果会比在代码文件里查看舒服并且利于阅读，于是我更加方便地阅读了解了里面的资料并继续进行开发
虽然要了解这个方法的参数什么的细节我甚至还能直接打开源代码去看，不也是有注释嘛，还有工作代码查看呢！可是在代码目录里跳来跳去有时候其实不是很顺利的，因为你关联的一个代码目录可能比较远，打开的跳转操作成本让人很心塞
在你没有源代码的时候才迫不得已去看API文档
没错，就像上面所说，如果自己手上有源码，很多普通开发者其实会更快地去选择查看源代码，至少在PHP这块非常容易做到
然而如果是Java、C++以及压缩了的JS里，你可能根本没办法看注释对吧，于是这些语言的程序员通常都比较有强烈的API文档查看意识
所以也暗示了API文档对于开源项目是极其重要的东西，因为开源项目要面向公众，API文档一般以html的形式存在，可以直接部署为在线文档，让广大开发者可以在需要的时候实现在线速查
有个秘密，一般人我不告诉他
¶
能看到这里，我也是服了你，有个秘密，一般人。。。
那就是我在项目里其实比较重视生成文档的
尽管对于普通程序员来说，实际上项目里的成员不咋看，然而有一个现状是大部分菜鸟会抱怨自己的公司生产管理不规范什么的
比如说：产品几乎是没有具体需求就叫人家去开发，数据库设计也没有审核，代码又没有统一风格，也没有测试人员，美工的画风老是不统一……
他们大部分其实都因为是在创业公司所以才有这样的报怨，有时候有些流程确实难以做到尽善尽美
作为混迹于创业公司的我，除了尽量把不规范的事情规范起来以外，还使用生成API文档这样的行为来给普通程序员一种“哇，这公司的项目挺有模有样的，竟然还有代码文档！不错不错”从而增加对企业的信心（然后这种感觉在不久后当然会消失，只是让普通程序员眼前一亮的东西而已）
说不好听的，这叫装B 
可是作为越来越熟练的PHP程序员，作为追求卓越的工程师，我们怎能连PHPDoc都不会？以后你进了大公司，你还不懂PHPDoc，或者写得很不像样，那些大公司的牛程序员怎么看你这个初来乍到的新人？
我不敢想像，至少我觉得，要体现我们专业的一面，PHPDoc一些常用的知识面必须懂
其实就算是面试时别人要看你的代码，一看到你有规范的PHPDoc注释都觉得你这个人的含金量高一点了吧，因为你这样的注释也能清楚地告诉其他团队成员这些代码是怎么一回事，参数的类型、说明、相关参考、返回值。。。我觉得写好注释————是一种态度