内容简介:好的语义表达是团队协作中高效迭代的润滑剂,好的语义表达是线上未知代码问题排查的指南针。不要让其他人读不懂你的代码,其他人可能就是一周后的你。时刻以“如果你写的这段代码出现故障,一个陌生人接手你的代码需要多久能处理完这个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提出用神经网络搜索实现语义分割
- 语义网络
本站部分资源来源于网络,本站转载出于传递更多信息之目的,版权归原作者或者来源机构所有,如转载稿涉及版权问题,请联系我们。
编程的修炼(中英双语)
[荷]Edsger W. Dijkstra / 裘宗燕 / 电子工业出版社 / 2013-7 / 79.00元
本书是图灵奖获得者Edsger W. Dijkstra在编程领域里的经典著作中的经典。作者基于其敏锐的洞察力和长期的实际编程经验,对基本顺序程序的描述和开发中的许多关键问题做了独到的总结和开发。书中讨论了顺序程序的本质特征、程序描述和对程序行为(正确性)的推理,并通过一系列从简单到复杂的程序的思考和开发范例,阐释了基于严格的逻辑推理开发正确可靠程序的过程。 本书写于20世纪70年代中后期,但......一起来看看 《编程的修炼(中英双语)》 这本书的介绍吧!