写在开头
本篇文章巨长，如果你比较“懒”，来我讲给你听（直播中有更多细节）——回放地址：
https://segmentfault.com/l/1500000018225727
看完这个还不过瘾？学习使你快乐？还想学习？快上车：
https://segmentfault.com/ls/1650000011318558
开始
好的语义表达是团队协作中高效迭代的润滑剂，好的语义表达是线上未知代码问题排查的指南针。
不要让其他人读不懂你的代码，其他人可能就是一周后的你。时刻以“如果你写的这段代码出现故障，一个陌生人接手你的代码需要多久能处理完这个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
*/
