深圳幻海软件技术有限公司 欢迎您！
更多

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

2023-02-26

this data key
好的语义表达是团队协作中高效迭代的润滑剂，好的语义表达是线上未知代码问题排查的指南针。本篇文章巨长，如果你比较“懒”，来我讲给你听(直播中有更多细节)回放地址看完这个还不过瘾?学习使你快乐?还想学习?快上车不要让其他人读不懂你的代码，其他人可能就是一周后的你。时刻以“如果你写的这段代码出现故障，一个

好的语义表达是团队协作中高效迭代的润滑剂，好的语义表达是线上未知代码问题排查的指南针。

本篇文章巨长，如果你比较“懒”，来我讲给你听(直播中有更多细节) 回放地址

看完这个还不过瘾?学习使你快乐?还想学习?快上车

不要让其他人读不懂你的代码，其他人可能就是一周后的你。时刻以“如果你写的这段代码出现故障，一个陌生人接手你的代码需要多久能处理完这个bug”来监督自己。

日常中应该多多刻意提升自己语义表达，百利而无一害。那么我们应该从哪些细节去做好语义表达呢?  

 

以下代码全为我的艺术创作，不属于任何实际项目

命名

案例1 

function getGoods($query, $shopId) 
{ 
    $goodsId = Goods::add($query["uid"], $query["name"]); 
    return Shop::add($goodsId, $shopId); 
} 
 
class Goods 
{ 
    public static function add($uid, $name) 
    { 
        $id = mt_rand(1, 100000); 
        return $id; 
    } 
} 
 
class Shop 
{ 
    public static function add($goodsId, $shopId) 
    { 
        $id = mt_rand(1, 100000); 
        return $id; 
    } 
}  

  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.
  • 9.
  • 10.
  • 11.
  • 12.
  • 13.
  • 14.
  • 15.
  • 16.
  • 17.
  • 18.
  • 19.
  • 20.
  • 21.
  • 22.
  • 23.

 

案例2 

function getUserInfo($teamId, $youId = []) 
{  
}  

  • 1.
  • 2.
  • 3.

如果仅仅有这个函数名和参数名，谁能猜到参数的意义呢? 

 

案例3

class Db 
{ 
    /** 
     * @param string $table 数据库表名 
     * @param array  $data  新增数据 
     * 
     * @return int 新增主键 
     */ 
    public static function insert(string $table, array $data) 
    { 
        $id = mt_rand(1, 1000); 
        return $id; 
    } 
} 
 
class ViewLogStore 
{ 
    private $table = "view_log"; 
 
    function setHistory($data) 
    { 
        Db::insert($this->table, $data); 
    } 
}  

  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.
  • 9.
  • 10.
  • 11.
  • 12.
  • 13.
  • 14.
  • 15.
  • 16.
  • 17.
  • 18.
  • 19.
  • 20.
  • 21.
  • 22.
  • 23.
  • 24.

 

案例4

假如业务代码里有这些类 

class WechatUserModel{ 
} 
class WechatGroupModel{ 
} 
class WechatMessageModel{ 
}  

  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.

而我们查询数据库发现 

 

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

来自灵魂的拷问

 

注释

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

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

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

对象数组 

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

  • 1.
  • 2.
  • 3.
  • 4.

 

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

  • 1.

@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; 
    } 
}  

  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.
  • 9.
  • 10.
  • 11.
  • 12.
  • 13.
  • 14.
  • 15.
  • 16.
  • 17.
  • 18.
  • 19.
  • 20.
  • 21.
  • 22.
  • 23.

 

 

 

@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"], 
        ]; 
    } 
}  

  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.
  • 9.
  • 10.
  • 11.
  • 12.
  • 13.
  • 14.
  • 15.
  • 16.
  • 17.
  • 18.
  • 19.

 

 

 

注释其他注意事项

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

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

函数、方法

案例1

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

找到一个开源软件里面的代码，功能非常抢到，但是这个方法内容太多，一些不足点我标注出来了。 

 

 

 

案例2

拿上面我举例子，还记得下面这种图吗? 

 

优化方案1 

class ArrayUtils{ 
    public static function fetch($arr, $keys, $setNull = false) 
    { 
        $ret = array(); 
        foreach($keys as $key) 
        { 
            if ($setNull) 
            { 
                $ret[$key] = $arr[$key]; 
            } 
            else 
            { 
                isset($arr[$key]) && $ret[$key] = $arr[$key]; 
            } 
        } 
        return $ret; 
    } 
} 
 
 
class ViewLogStore 
{ 
    private $table = "view_log"; 
 
    function record($data) 
    { 
        $fields = array( 
            'uid', 
            'url', 
            'referer', 
            'created_time' 
        ); 
        $data = ArrayUtils::fetch($data, $fields); 
        Db::insert($this->table, $data); 
    } 
}  

  • 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.

优化方案2 

class Db 
{ 
    /** 
     * @param string $table 数据库表名 
     * @param Entity $data  新增对象 
     * 
     * @return int 新增主键 
     */ 
    public static function insert(string $table, Entity $data) 
    { 
        $array = $data->toArray(); 
        var_export($array); // test 
 
        $id = mt_rand(1, 1000); 
        return $id; 
    } 
} 
 
class ArrayUtils 
{ 
    /** 
     * 针对成员都是私有属性的对象 
     * 
     * @param      $obj 
     * @param bool $removeNull 去掉空值 
     * @param bool $camelCase 
     * 
     * @return array 
     */ 
    public static function Obj2Array($obj, $removeNull = true, $camelCase = true) 
    { 
        $reflect = new \ReflectionClass($obj); 
        $props = $reflect->getProperties(\ReflectionProperty::IS_PUBLIC | \ReflectionProperty::IS_PRIVATE | \ReflectionProperty::IS_PROTECTED); 
 
        $array = []; 
        foreach ($props as $prop) { 
            $prop->setAccessible(true); 
            $key = $prop->getName(); 
 
            // 如果不是驼峰命名方式，就把对象里面的 createTime 转成 create_time 
            if (!$camelCase) { 
                $key = preg_replace_callback("/[A-Z]/", function ($matches) { 
                    return "_" . strtolower($matches[0]); 
                }, $key); 
                $key = ltrim($key, "_"); 
            } 
 
            $value = $prop->getValue($obj); 
 
            if ($removeNull == true && $value === null) { 
                continue; 
            } 
 
            if (is_object($value)) { 
                $value = self::Obj2Array($value); 
            } 
 
            $array[$key] = $value; 
        } 
 
        return $array; 
    } 
} 
 
class Entity 
{ 
    public function toArray(){ 
        return ArrayUtils::Obj2Array($this); 
    } 
} 
 
class ViewLogEntity extends Entity 
{ 
    /** 
     * @var int 
     */ 
    private $uid; 
 
    /** 
     * @var string 
     */ 
    private $url; 
 
    /** 
     * @var string 
     */ 
    private $referer; 
 
    /** 
     * @var string 
     */ 
    private $createdTime; 
 
    /** 
     * @param int $uid 
     */ 
    public function setUid(int $uid) 
    { 
        $this->uid = $uid; 
    } 
 
    /** 
     * @param string $url 
     */ 
    public function setUrl(string $url) 
    { 
        $this->url = $url; 
    } 
 
    /** 
     * @param string $referer 
     */ 
    public function setReferer(string $referer) 
    { 
        $this->referer = $referer; 
    } 
 
    /** 
     * @param string $createdTime 
     */ 
    public function setCreatedTime(string $createdTime) 
    { 
        $this->createdTime = $createdTime; 
    } 
} 
 
 
class ViewLogStore 
{ 
    private $table = "view_log"; 
 
    function record(ViewLogEntity $viewLogEntity) 
    { 
        Db::insert($this->table, $viewLogEntity); 
    } 
} 
 
// 测试 
 
$viewLogEntity = new ViewLogEntity(); 
$viewLogEntity->setUid(1); 
$viewLogEntity->setReferer("https://mengkang.net"); 
$viewLogEntity->setUrl("https://segmentfault.com/l/1500000018225727"); 
$viewLogEntity->setCreatedTime(date("Y-m-d H:i:s",time())); 
 
$viewLogStore = new ViewLogStore(); 
$viewLogStore->record($viewLogEntity);  

  • 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.
  • 61.
  • 62.
  • 63.
  • 64.
  • 65.
  • 66.
  • 67.
  • 68.
  • 69.
  • 70.
  • 71.
  • 72.
  • 73.
  • 74.
  • 75.
  • 76.
  • 77.
  • 78.
  • 79.
  • 80.
  • 81.
  • 82.
  • 83.
  • 84.
  • 85.
  • 86.
  • 87.
  • 88.
  • 89.
  • 90.
  • 91.
  • 92.
  • 93.
  • 94.
  • 95.
  • 96.
  • 97.
  • 98.
  • 99.
  • 100.
  • 101.
  • 102.
  • 103.
  • 104.
  • 105.
  • 106.
  • 107.
  • 108.
  • 109.
  • 110.
  • 111.
  • 112.
  • 113.
  • 114.
  • 115.
  • 116.
  • 117.
  • 118.
  • 119.
  • 120.
  • 121.
  • 122.
  • 123.
  • 124.
  • 125.
  • 126.
  • 127.
  • 128.
  • 129.
  • 130.
  • 131.
  • 132.
  • 133.
  • 134.
  • 135.
  • 136.
  • 137.
  • 138.
  • 139.
  • 140.
  • 141.
  • 142.
  • 143.
  • 144.
  • 145.
  • 146.
  • 147.

案例3

这还是函数吗?(不仅仅是语义，属于错误) 

/** 
 * @method mixed fetchList(string $sql, array $argv); 
 */ 
class Model 
{ 
 
    public function __construct($table) 
    { 
 
    } 
} 
 
function getUserList($startId, $lastId, $limit = 100) 
{ 
    if ($lastId > 0) { 
        $startId = $lastId; 
    } 
 
    $sql = "select * from `user` where id > ? order by id asc limit ?,?"; 
 
    $model = new Model('user'); 
    return $model->fetchList($sql, [intval($startId), intval($limit)]); 
}  

  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.
  • 9.
  • 10.
  • 11.
  • 12.
  • 13.
  • 14.
  • 15.
  • 16.
  • 17.
  • 18.
  • 19.
  • 20.
  • 21.
  • 22.
  • 23.

$startId和$lastId两个参数重复

案例4

尽量减少参数引用 

function bad($input1, $input2, &$input3) 
{ 
    //...logic 
 
    $input3 = "xxx"; 
 
    return true; 
}  

  • 1.
  • 2.
  • 3.
  • 4.
  • 5.
  • 6.
  • 7.
  • 8.

案例5

参数类型明确，返回值类型明确，不要出现 mixed。这个我直接拿官方的函数来举例，对权威也要有怀疑的眼光。纯属个人看法。 

 

 

 

案例6 

 

 

 

上面例子中你会发现这个addUser写得不想一个函数(方法)而像一个远程api接口。而且在右边的代码中需要每次使用的时候都要用is_array来判断。这是非常不友好的语义表达。PHP Java 这样的高级语言有异常，我们要善用异常。 

 

 

 

好的语义表达是团队协作中高效迭代的润滑剂，好的语义表达是线上未知代码问题排查的指南针。这篇博客到这里就结束了，不知道你是否有一些收获呢? 

 

 

如何两天时间上线一款AI应用？
用自己的编程语言实现了一个网站（增强版）