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

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

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

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

不要让其他人读不懂你的代码，其他人可能就是为名一周后的你。时刻以“如果你写的优秀语义这段代码出现故障，一个陌生人接手你的程师代码需要多久能处理完这个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;     } }  

 

案例2 

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

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

 

案例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);     } }  

 

案例4

假如业务代码里有这些类 

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

而我们查询数据库发现 

 

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

来自灵魂的拷问

 

注释

说完命名，下面说下注释。注释里还有什么学问?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 烂代码多的去了。

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

 

案例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);     } }  

优化方案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);  

案例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)]); }  

$startId和$lastId两个参数重复

案例4

尽量减少参数引用 

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

案例5

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

 

案例6 

 

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

 

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

云服务器

很赞哦!（59257）