如何成为一名优秀的工程师（语义篇）(2)

而我们查询数据库发现

这样我们根据业务代码就非常不方便找到对应的表，而且其他人接手我们项目的时候，也会摸不着头脑。或者说这可能是三个人三次迭代开发造成的，那么他们彼此都没有去参考前面人的命名规则。

来自灵魂的拷问

注释

说完命名，，下面说下注释。注释里还有什么学问?Are you kidding me?

一个数组对象成员，你知道怎么写吗?

类的魔术方法调用的注释，你知道怎么写吗?

对象数组 

/** 
 * @var Ads[] 
 */ 
public $adsList = [];  

$blocks = [];/** @var $blocks Block[] **/  

@method 的使用

/** 
 * @link http://manual.phpdoc.org/HTMLframesConverter/default/ 
 * 
 * @method static int search(string $query, $limit = 10, $offset = 0) 
 */ 
class SearchServiceProxy 
{ 
    public static function __callStatic($method, $arguments) 
    { 
        if (!method_exists("SearchService", $method)) { 
            throw new \LogicException(__CLASS__ . "::" . $method . " not found"); 
        } 
 
        try { 
            $data = call_user_func_array(["SearchService", $method], $arguments); 
        } catch (\Exception $e) { 
            error_log($e->getMessage()); 
            return false; 
        } 
 
        return $data; 
    } 
}  

@deprecated 使用 

class SearchService 
{ 
 
    /** 
     * @param string $query 
     * @param int    $limit 
     * @param int    $offset 
     * 
     * @return array 
     * @deprecated 
     */ 
    public static function search(string $query, $limit = 10, $offset = 0) 
    { 
        return [ 
            ["id" => 1, "aaa"], 
            ["id" => 2, "bbb"], 
        ]; 
    } 
}  

注释其他注意事项

注释解释张冠李戴，方法名更新，方法的功能业务注释没更新;复制别人的代码把 @author 信息也复制过来了，错误了还要把锅甩给别人。

注释更多参考 http://manual.phpdoc.org/HTML...

函数、方法

案例1

先说明一句，不好的代码不妨碍它成为一个优秀的软件。PHP MySQL 烂代码多的去了。

（编辑：ASP站长网）