内容简介:好的语义表达是团队协作中高效迭代的润滑剂,好的语义表达是线上未知代码问题排查的指南针。不要让其他人读不懂你的代码,其他人可能就是一周后的你。时刻以“如果你写的这段代码出现故障,一个陌生人接手你的代码需要多久能处理完这个bug”来监督自己。日常中应该多多刻意提升自己语义表达,百利而无一害。那么我们应该从哪些细节去做好语义表达呢?
好的语义表达是团队协作中高效迭代的润滑剂,好的语义表达是线上未知代码问题排查的指南针。
不要让其他人读不懂你的代码,其他人可能就是一周后的你。时刻以“如果你写的这段代码出现故障,一个陌生人接手你的代码需要多久能处理完这个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/HTMLframesConverter/default/
函数、方法
案例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 这样的高级语言有异常,我们要善用异常。
好的语义表达是团队协作中高效迭代的润滑剂,好的语义表达是线上未知代码问题排查的指南针。这篇博客到这里就结束了,不知道你是否有一些收获呢?
放三个二维码
累死啦,原创博客不容易,如果觉得不错,可以打赏下哈。谢谢。
以上就是本文的全部内容,希望对大家的学习有所帮助,也希望大家多多支持 码农网
猜你喜欢:- 消息队列的消费语义和投递语义
- 剑桥构建视觉“语义大脑”:兼顾视觉信息和语义表示
- 新瓶装旧酒:语义网络,语义网,链接数据和知识图谱
- 超强语义分割算法!基于语义流的快速而准确的场景解析
- 语义分割领域开山之作:Google提出用神经网络搜索实现语义分割
- 语义网络
本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们。
大数据技术原理与应用
林子雨 / 人民邮电出版社 / 2015-8-1 / 45.00
大数据作为继云计算、物联网之后IT行业又一颠覆性的技术,备受关注。大数据处不在,包括金融、汽车、零售、餐饮、电信、能源、政务、医疗、体育、娱乐等在内的社会各行各业,都融入了大数据的印迹,大数据对人类的社会生产和生活必将产生重大而深远的影响。 大数据时代的到来,迫切需要高校及时建立大数据技术课程体系,为社会培养和输送一大批具备大数据专业素养的高级人才,满足社会对大数据人才日益旺盛的需求。本书定......一起来看看 《大数据技术原理与应用》 这本书的介绍吧!