代码整洁之道

一、有意义的命名

1. 名副其实

// 差劲：谁知道$arr是什么？$v是什么？
foreach ($arr as $v) {
      // Do someting...
}
// 优秀：一眼就看出来这是一段循环处理订单列表的代码
foreach ($orders as $order) {
    // Do someting
}

2. 避免误导

// 差劲：不会真有人变量用 $l、$O 吧？
$l = 1;
$O = 0;
// 优秀：使用符合语境的变量
$accounts = [];

3. 做有意义的区分

// 差劲：3个变量都能表达用户信息，那到底区别是什么？
$account = [];
$accountInfo = [];
$accountDetail = [];
// 优秀：直接用$account
$account = [];

4. 使用读的出来的名称

// 举例：定义一个“消费者”变量
// 差劲：用拼音、乱翻译、拼音英文混用、用其他国家的语言，用方言...
$xiaofeizhe = [];
$consuming = [];
$consumer_liebiao = [];
$o_kya_ku_sa_ma = [];
$xiu_fai_zhe = [];
// 优秀：使用符合语境的变量
$consumers = [];
$consumer_list = [];

5. 使用可搜索的名称

// 差劲：用短单词、具体数值。谁知道7代表了啥？我要怎么做才能快速定位到这个代码并修改？
if ($days > 7) {
      // Do someting...
}
// 优秀：使用常量、读取配置
const MAX_DAYS_FOR_BOOKING = 7;
if ($days > MAX_DAYS_FOR_BOOKING) {
        // Do someting...
}

6. 类名和对象名应该是名词或名词短语

// 差劲：使用其他类型修饰词
$invoke = new Invoker();
$invoke->invoke();
// 优秀：使用符合语境的变量
$invoker = new Invoker();
$invoker->invoke();

7. 方法名应当是动词或动词短语

// 差劲：使用其他类型修饰词
class Printer {
    public function printers(): array {
            // Do someting
    }
}
// 优秀：使用符合语境的变量
class Printer {
    public function getPrinters(): array {
            // Do someting
    }
}

8. 不要添加没用的语境

// 差劲：输入一个Alipay，IDE提示一堆的列表
class AlipayAccountExrateAdviceAcceptRequest {}
class AlipayAccountExrateAllclientrateQueryRequest {}
class AlipayAccountExrateRatequeryRequest {}
// 优秀：善用命名空间
namespace Alipay\Account\Exrate;
class AdviceAcceptRequest {}
class AllclientrateQueryRequest {}
class RatequeryRequest {}

二、函数

1. 越短小越好、只做一件事

// 差劲：一个屏幕根本看不完
function refundOrder($order) {
        // 此处省略一堆if else swtich混合的几百行、甚至上千行代码
}
// 优秀：函数式编程、面向对象编程
class OrderService {
      protected $order;
      protected $operator;
        public function __construct(OrderRepository $order) {
            $this->order = $order;
    }
      public function setOperator(Operator $operator) {
                $this->operator = $operator;
    }
}
class RefundService extends OrderService {
      public function refund(): bool {
            // Do something
    }
      public function validate(): bool {
          // Do something
    }
}

2. 使用描述性名称

// 差劲：让人摸不着头脑的命名，不看函数体，我能否理解成，往数组$a里面追加$b
function addNumber($a, $b) {
        return $a + $b;
}
// 优秀：使用符合语境的变量，函数动作就是要求和，名字直接就用求和的英文
function sum($a, $b) {
        return $a + $b;
}

3. 函数参数数量越少越好

// 差劲：一个函数4个以上的参数
function sendCoupon($account_id, $coupons, $link_type, $link_id) {
      // Do something
}
// 优秀：函数式编程、面向对象编程
class SendCouponEvent {
      private $accounts;
    private $coupons;
      private $link_type;
      private $link_id;
      public function setAccounts(AccountRepository $accounts) {
            $this->accounts = $accounts;
    }
      public function setCoupons(CouponRepository $coupons) {
            $this->coupons = $coupons;
    }
      public function setLink(int $link_type, int $link_id) {
            $this->link_type = $link_type;
          $this->link_id = $link_id;
    }
      public function send() {
            // Do something
    }
}
$event = new SendCouponEvent();
$event->setAccounts($accounts);
$event->setCoupons($coupons);
$event->setLink($link_type, $link_id);
$event->send();

4. 分割指令与询问

// 差劲：指令与询问合并
if (setUser("user", $user)) {
        // Do something
}
// 优秀：指令与询问分割
if (isEmpty($user)) {
        saveUser("user", $user);
}

三、注释

1. 警示注释

// 差劲：测试或危险操作代码不写注释
function updateUsersScore() {
      Db::table("users")->where("id", ">", 0)->update(['score' => 0]);
}
// 优秀：告知其他人代码的目的
function updateUsersScore() {
      // 一键清空用户积分，仅测试使用，请勿在生产环境运行
      Db::table("users")->where("id", ">", 0)->update(['score' => 0]);
}

2. TODO

// 差劲：乱写TODO、TODO内容为空、长期不处理...
function testAddOrder() {
        // TODO
}
// 优秀：写真实会处理的TODO，如果长期未处理，直接删除！

3. 喃喃自语

// 差劲：根本不知道注释想表达什么，目的是什么
function testAddOrder() {
        try {
    } catch (Exception $e) {
            // 抛出异常了
    }
}
// 优秀：写清楚这个注释的目的是什么
function testAddOrder() {
        try {
    } catch (Exception $e) {
            // 抛出异常了，记录异常日志
          Log::write($e->getTraceAsString());
    }
}

4. 日志型注释

// 差劲：记录修改日志
function testAddOrder() {
        // 2021-01-01 生成商品
        // 2021-01-02 生成订单
      // 2021-01-03 订单退款
}
// 优秀：使用Git、SVN

5. 废话注释

// 差劲：变量或者函数名一下就能看出来是什么，非要写个注释
function testAddOrder() {
        $goods = [];//商品信息
      $order = [];//订单信息
}
// 优秀：变量或者函数命名已经符合语境，不要写多余解释

6. 位置标记

// 差劲：使用长字符串分割代码
class UserController {
        /************ 登录逻辑开始 *********/
      // 此处省略几百行代码
      /************ 登录逻辑结束 *********/
        /************ 注册逻辑开始 *********/
      // 此处省略几百行代码
      /************ 注册逻辑结束 *********/
}
// 优秀：删除无用注释、业务逻辑过于复杂可以拆分文件

7. 括号注释

// 差劲：在每个括号类型后面写无意义注释，仅用于标记
foreach ($users as $user) {
        if (isEmpty($user)) {
                // 此处省略几百行代码
        } //if
      // 此处省略几百行代码
}//foreach
// 优秀：函数式编程、面向对象编程

8. 注释掉的代码

// 差劲：直接注释原有代码
function addOrder() {
      $order = new OrderRepository();
        // 让人觉得这段代码可能是有用的，不能随意删除（实际已无用）
      // $order->setAmount($amount);
      $order->add();
      // 测试代码保留并提交，像个牛皮癣一样影响代码阅读与维护
      // halt($order);
}
// 优秀：无用代码直接删除！用Git管理历史记录！

9. 不明显的联系

// 差劲：注释没有表达到位。为什么要加200？200是什么东西？
function testSum($a) {
        // 此处需要加200
        return $a + 200;
}
// 优秀：使用有意义的命名

四、格式

编码风格指南：https://www.yuque.com/kubo/resources/frontend-style