现代化的PHP-写好注释

内容简介：现代化的PHP-写好注释

注释

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

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

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

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

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

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

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

<?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 就无法自动推导类型了：

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

以上就是本文的全部内容，希望本文的内容对大家的学习或者工作能带来一定的帮助，也希望大家多多支持 码农网

查看所有标签

猜你喜欢:

• 现代化网站的渗透测试
• 现代化 Android Pie: 安全与隐私
• Dahlia：一个现代化的 React 框架
• 对现代化网站的渗透测试的思考
• 来!狂撸一款PHP现代化框架 (一)
• 用现代化的方式开发一个图片上传工具

本站部分资源来源于网络，本站转载出于传递更多信息之目的，版权归原作者或者来源机构所有，如转载稿涉及版权问题，请联系我们。