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

好的语义表达是团队协作中高效迭代的润滑剂，好的语义表达是线上未知代码问题排查的指南针。不要让其他人读不懂你的代码，其他人可能就是一周后的你。时刻以“如果你写的这段代码出现故障，一个陌生人接手你的代码需要多久能处理完这个bug”来监督自己。日常中应该多多刻意提升自己语义表达，百利而无一害。那么我们应该从哪些细节去做好语义表达呢？以下代码全为我的艺术创作，不属于任何实际项目命名案例1function 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; }}案例2function getUserInfo($teamId, $youId = []){}如果仅仅有这个函数名和参数名，谁能猜到参数的意义呢？案例3class 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拿上面我举例子，还记得下面这种图吗？优化方案1class 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); }}优化方案2class 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 这样的高级语言有异常，我们要善用异常。好的语义表达是团队协作中高效迭代的润滑剂，好的语义表达是线上未知代码问题排查的指南针。这篇博客到这里就结束了，不知道你是否有一些收获呢？放三个二维码累死啦，原创博客不容易，如果觉得不错，可以打赏下哈。谢谢。