现代化的PHP-写好注释

注释

有个段子:程序员最恨写注释和不写注释的人。个人认为注释主要作用是方便别人或者自己以后能快速理解这段代码逻辑和提升开发效率,这样要说的是如何使用注释来提升开发效率。

众所周知,PHP 是弱类型语言,变量的类型是可以变的,但在实际业务中,一个变量或者函数的返回值往往是确定的,确定的类型能提升我们的编码效率,也能把一些低级的错误(弱类型不代表无类型)扼杀在摇篮里。

PHP 主要通过类型声明来说明变量的类型,PHP7 开始允许更多的函数参数类型限定。比如下面这个例子,声明入参是 int 类型,但使用了 array 函数来处理,PhpStorm 能给出实时的提醒。

调用函数参数错误的话也有提示:

但 PHP 会有隐式类型转换,如上面传入浮点数的时候并没有提示错误,因为这也是合理的。不过 PHP 可以开启严格模式来检查此类错误。

PHP 内置的类型声明基本上够用了,但一般使用注释来实现更加丰富的功能。PHPDoc 是注释 PHP 代码的非正式标准,它有许多不同的标记可以使用。PhpStorm 能根据函数/类方法自动生成基本的标记:

基本标记 @param@return 也很好理解,参数和返回值,作用和 PHP 自带的类型声明差不多,主要用来限制调用方传参和使用返回值。除了这两个标记之外,还有很多其它比较好用的标记。

Continue Reading…