资讯专栏INFORMATION COLUMN

上云采购季！| 2核2G4M爆款云服务器低至59元/年，更有多台、长期优惠，快来选购！

立即前往
首页/文章专栏/如何成为一名优秀的工程师（语义篇）

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

张金宝 / 2675人阅读

摘要：好的语义表达是团队协作中高效迭代的润滑剂，好的语义表达是线上未知代码问题排查的指南针。日常中应该多多刻意提升自己语义表达，百利而无一害。注释更多参考函数方法案例先说明一句，不好的代码不妨碍它成为一个优秀的软件。这是非常不友好的语义表达。

好的语义表达是团队协作中高效迭代的润滑剂，好的语义表达是线上未知代码问题排查的指南针。
本篇文章巨长，如果你比较“懒”，来我讲给你听（直播中有更多细节） 回放地址 看完这个还不过瘾？学习使你快乐？还想学习？快上车

不要让其他人读不懂你的代码，其他人可能就是一周后的你。时刻以“如果你写的这段代码出现故障，一个陌生人接手你的代码需要多久能处理完这个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 这样的高级语言有异常，我们要善用异常。

好的语义表达是团队协作中高效迭代的润滑剂，好的语义表达是线上未知代码问题排查的指南针。这篇博客到这里就结束了，不知道你是否有一些收获呢？

放三个二维码

累死啦，原创博客不容易，如果觉得不错，可以打赏下哈。谢谢。

GPU云服务器 云服务器 一名优秀 成为一名 如何成为全栈工程师 如何成为web前端工程师

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/30938.html

相关文章

  • 如何成为一名优秀的程序员

    摘要：前言罗子雄如何成为一名优秀设计师董明伟工程师的入门和进阶董明伟基于自己实践讲的知乎为新人提供了很多实用建议，他推荐的罗子雄如何成为一名优秀设计师的演讲讲的非常好，总结了设计师从入门到提高的优秀实践。 前言 罗子雄：如何成为一名优秀设计师 董明伟：Python 工程师的入门和进阶 董明伟基于自己实践讲的知乎live为Python新人提供了很多实用建议，他推荐的罗子雄：如何成为一名优秀...

    keelii 评论0 收藏0

  • 如何成为一名优秀的web前端工程师（前端攻城师）？

    摘要：我从没有听到有人问如何做一名优秀甚至卓越的前端工程师。作为一个优秀的前端工程师还需要深入了解以及学会处理的这些缺陷。再者，优秀的前端工程师需要具备良好的沟通能力，因为前端工程师至少都要满足四类客户的需求。 　　我所遇到的前端程序员分两种： 　　第一种一直在问：如何学习前端？ 　　第二种总说：前端很简单，就那么一点东西。 　　我从没有听到有人问：如何做一名优秀、甚至卓越的WEB前端工程师...

    Turbo 评论0 收藏0

  • 如何成为一名优秀的web前端工程师（前端攻城师）？

    摘要：我从没有听到有人问如何做一名优秀甚至卓越的前端工程师。作为一个优秀的前端工程师还需要深入了解以及学会处理的这些缺陷。再者，优秀的前端工程师需要具备良好的沟通能力，因为前端工程师至少都要满足四类客户的需求。 　　我所遇到的前端程序员分两种： 　　第一种一直在问：如何学习前端？ 　　第二种总说：前端很简单，就那么一点东西。 　　我从没有听到有人问：如何做一名优秀、甚至卓越的WEB前端工程师...

    rubyshen 评论0 收藏0

  • 如何成为一名优秀的web前端工程师（前端攻城师）？

    摘要：我从没有听到有人问如何做一名优秀甚至卓越的前端工程师。作为一个优秀的前端工程师还需要深入了解以及学会处理的这些缺陷。再者，优秀的前端工程师需要具备良好的沟通能力，因为前端工程师至少都要满足四类客户的需求。 　　我所遇到的前端程序员分两种： 　　第一种一直在问：如何学习前端？ 　　第二种总说：前端很简单，就那么一点东西。 　　我从没有听到有人问：如何做一名优秀、甚至卓越的WEB前端工程师...

    mingzhong 评论0 收藏0

发表评论

登陆后可评论

0条评论

张金宝

男|高级讲师
我要私信

TA的文章

阅读更多
最新活动
阅读需要支付1元查看
<