现代化的PHP-写好注释

目录

• 注释
• 注解
• 参考资料

注释

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

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

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

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

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

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

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

 

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60

<?php /** * @author A Name <a.name@example.com> 2018-01-01 * @link https://docs.phpdoc.org/references/phpdoc/tags/link.html */   namespace Demo; use Exception;   /** * Class DemoClass * @package Demo * @version 1.0 */ class DemoClass {     /**      * @var array      */     public $names = [];       /**      * methodA      * @param int $a param a      * @return int      * @throws Exception when {$a} < 0      */     function methodA(int $a)     {         if($a < 0)         {             /**              * @see Exception::getMessage()              */             throw new Exception('test');         }           return $a + 1;     }       /**      * @deprecated      * @since 1.0 deprecated      * @todo del it      * TODO del it      */     function methodB(){} }   $demoA = new DemoClass(); $demoA->methodA([]); array_keys($demoA->methodA(1)); $demoA->methodB(); $demoA->methodA($demoA->names);   $str = 'DemoClass'; /** * @var DemoClass $demoB */ $demoB = new $str();

@author，顾名思义就是说明代码的作者。留下你的大名和时间，以后有问题了好找你。

`@link`，主要是用来放一些相关的链接。

`@package`，包名。`@version`，版本。

`@Exception`，表示抛出的异常，当调用方未正确处理异常时会有提示。

@see，表示去这里看相关的参考，有点像@link，一般用作指向代码，方便 IDE 跳转查看。

`@deprecated`，表示这个方法以及弃用了。调用弃用的代码会有提示：

`@since`，记录版本变化，比如上面的例子说明 1.0 版本弃用了这个方法。

@todo和`TODO`（PhpStorm 标记语法），表示这里还需优化改动一下，但现在还没改（以后估计也不会改了）。在提交代码时 PhpStorm 会提示你还有几个 todo。

`@var`，声明变量的类型。这个标记看似鸡肋（一般 IDE 都有类型推导），但在 PHP 动态语言中有时非常有用。比如下面这个例子类名是字符串，IDE 就无法自动推导类型了：

这是我们可以显式的注释一下：

这样就能使用自动提示了，提升了开发效率。

这里举例说明了几个常用的注释标记，完整列表以及文档生成可查看 phpdoc 官网教程。

注解

了解过 Java Spring 的同学会发现，它的注解（Annotation）特性非常强大，极大了提升了开发效率，也使代码变得简洁。PHP 也有类似的规范（PSR-5，起草阶段），一些现代化的框架已经有相关实现了。不过此特征一般都是通过反射、注入实现，PHP 传统的 FPM 运行模式在此存在性能问题，实际应用不广。laravel 甚至在主干上移除了注解的支持。

不过一些不是基于 FPM（原生 PHP） 的框架，对此就支持的比较好。比如基于 swoole 的 Swoft，基于 C 扩展的 Phalcon。

我相信随着 PHP 本身不断优化（期待 JIT）以及各种框架百花齐放，未来会更好。

参考资料

http://laravel-china.github.io/php-the-right-way/#documenting

https://docs.phpdoc.org/

http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration