IDEA激活码 (2024-03-27)
全网最全idea主题,phpstorm主题,webstorm主题免费下载

phpDocs——躲在角落里的核心特性

docs简介

很多语言都有通过代码注释(类注释、方法注释、成员注释)来生成接口文档的机制,比如java、php。这个机制包括两部分,一部分是代码注释的规范;一部分是生成文档的工具。就是说首先你要按照注释规范规定的风格书写注释,然后使用对应工具就可以生成接口文档(或者说说类结构描述文档)来供别人或自己查看。

php作为弱类型语言,phpDocs除了可以生成接口文档之外,还承载了语法检查等更重要的作用。因为是弱类型,所以没有在语言级别做某些限制,比如函数的参数签名中如果不声明变量类型,那么不管你传入的是什么类型的变量,则idea永远不会提示你代码异常,直到运行时报错。这在代码安全性上是很重要的问题。 

自动生成phpDocs

开发过程中我们可能习惯先写好方法签名才会写注释。当然手写注释非常麻烦,phpstorm提供了生成注释的功能,在类的任意部分(方法名前、类名前、成员名前)输入/**然后按回车即可自动生成docs。

自动更新phpDocs

写好的注释需要修改,比如要给一个方法新增一个参数,那么在参数签名中添加过此参数之后会发现phpstorm在此参数下划了黄色波浪线(给出警告),则在此参数上使用快捷键【自动补全】则会弹出自动更新phpdocs的选项,选择此选项即可自动更新docs,包括参数名,参数类型等。当然,当你重构参数名的时候,docs也会自动更新。

laravel中使用phpDocs提高开发效率

docs还有一个非常核心的功能就是代码提示。可以给类以phpDocs的方式提供成员声明。比如给类Person提供一个成员声明,则可以实现自动补全,给类提供方法docs也可以达到代码提示的效果,并且phpstorm将会自动将此成员认定为是类结构的一部分。比如下图中的Person类中的name成员。此成员支持重构。有些工具比如ide-helper就是使用此机制来提高laravel开发效率。

总结

phpDocs不仅能提高代码可读性,并且可以大幅提升开发效率和代码安全性。没有理由不用使用phpDocs,因为这是对php作为弱类型语言弱点的核心补充,可以说是接上了php的一条断腿。

题目说此特性是【躲在角落里的】是说明,很多人都没有认识到docs的重要性和在php生态中的核心性,这很可悲。

 

idea激活码 、phpstorm、pycharm、datagrip注册码获取 http://www.jetbrains-active.com/article/4.html

 

热门评论

    暂无