如何成為一名優秀的工程師（語義篇）
作者：佚名
好的語義表達是團隊協作中高效迭代的潤滑劑，好的語義表達是線上未知代碼問題排查的指南針。
好的語義表達是團隊協作中高效迭代的潤滑劑，好的語義表達是線上未知代碼問題排查的指南針。
本篇文章巨長，如果你比較“懶”，來我講給你聽(直播中有更多細節) 回放地址
看完這個還不過癮?學習使你快樂?還想學習?快上車
不要讓其他人讀不懂你的代碼，其他人可能就是一周后的你。時刻以“如果你寫的這段代碼出現故障，一個陌生人接手你的代碼需要多久能處理完這個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 這樣的高級語言有異常，我們要善用異常。
好的語義表達是團隊協作中高效迭代的潤滑劑，好的語義表達是線上未知代碼問題排查的指南針。這篇博客到這里就結束了，不知道你是否有一些收獲呢?
責任編輯：龐桂玉
來源：
segmentfault
