PHP简洁之道

calendar Apr 14, 2019 · 17 分钟 阅读

原文：https://github.com/jupeter/clean-code-php

译文：https://github.com/nineyang/clean-php-code

前言

前几天在GitHub看到一篇写PHP简洁之道的译文，觉得还不错，所以转在了自己的博客中，只不过有一些地方好像没有翻译，再加上排版上的一些小问题，所以决定自己翻译一遍

变量

  • 使用更有意义和更加直白的命名方式

不友好的:

1$ymdstr = $moment->format('y-m-d');

友好的:

1$currentDate = $moment->format('y-m-d');
  • 对于同一实体使用相同变量名

不友好的:

1getUserInfo();
2getUserData();
3getUserRecord();
4getUserProfile();

友好的:

1getUser();
  • 使用可以查找到的变量

我们读的代码量远比我们写过的多。因此，写出可阅读和便于搜索的代码是及其重要的。在我们的程序中写出一些难以理解的变量名 到最后甚至会让自己非常伤脑筋。 因此，让你的名字便于搜索吧。

不友好的:

1// 这里的448代表什么意思呢？
2$result = $serializer->serialize($data, 448);

友好的:

1$json = $serializer->serialize($data, JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT | >JSON_UNESCAPED_UNICODE);
  • 使用解释型变量

不友好的

1$address = 'One Infinite Loop, Cupertino 95014';
2$cityZipCodeRegex = '/^[^,]+,\s*(.+?)\s*(\d{5})$/';
3preg_match($cityZipCodeRegex, $address, $matches);
4
5saveCityZipCode($matches[1], $matches[2]);

不至于那么糟糕的:

稍微好一些，但是这取决于我们对正则的熟练程度。

1$address = 'One Infinite Loop, Cupertino 95014';
2$cityZipCodeRegex = '/^[^,]+,\s*(.+?)\s*(\d{5})$/';
3preg_match($cityZipCodeRegex, $address, $matches);
4
5[, $city, $zipCode] = $matches;
6saveCityZipCode($city, $zipCode);

友好的:

通过对子模式的重命名减少了我们对正则的熟悉和依赖程度。

1$address = 'One Infinite Loop, Cupertino 95014';
2$cityZipCodeRegex = '/^[^,]+,\s*(?<city>.+?)\s*(?<zipCode>\d{5})$/';
3preg_match($cityZipCodeRegex, $address, $matches);
4
5saveCityZipCode($matches['city'], $matches['zipCode']);
  • 嵌套无边，回头是岸

太多的if else嵌套会让你的代码难以阅读和维护。更加直白的代码会好很多。

  1. demo1

不友好的:

 1function isShopOpen($day): bool
 2{
 3   if ($day) {
 4       if (is_string($day)) {
 5           $day = strtolower($day);
 6           if ($day === 'friday') {
 7               return true;
 8           } elseif ($day === 'saturday') {
 9               return true;
10           } elseif ($day === 'sunday') {
11               return true;
12           } else {
13               return false;
14           }
15       } else {
16           return false;
17       }
18   } else {
19       return false;
20   }
21}

友好的:

 1function isShopOpen(string $day): bool
 2{
 3   if (empty($day)) {
 4       return false;
 5   }
 6
 7   $openingDays = [
 8       'friday', 'saturday', 'sunday'
 9   ];
10
11   return in_array(strtolower($day), $openingDays, true);
12}
  1. demo2

不友好的:

 1function fibonacci(int $n)
 2{
 3   if ($n < 50) {
 4       if ($n !== 0) {
 5           if ($n !== 1) {
 6               return fibonacci($n - 1) + fibonacci($n - 2);
 7           } else {
 8               return 1;
 9           }
10       } else {
11           return 0;
12       }
13   } else {
14       return 'Not supported';
15   }
16}

友好的:

 1function fibonacci(int $n): int
 2{
 3   if ($n === 0 || $n === 1) {
 4       return $n;
 5   }
 6
 7   if ($n > 50) {
 8       throw new \Exception('Not supported');
 9   }
10
11   return fibonacci($n - 1) + fibonacci($n - 2);
12}
  • 避免使用不合理的变量名

别让其他人去猜你的变量名的意思。 更加直白的代码会好很多。

不友好的:

 1$l = ['Austin', 'New York', 'San Francisco'];
 2
 3for ($i = 0; $i < count($l); $i++) {
 4   $li = $l[$i];
 5   doStuff();
 6   doSomeOtherStuff();
 7   // ...
 8   // ...
 9   // ...
10   // 等等，这个$li是什么意思?
11   dispatch($li);
12}

友好的:

 1$locations = ['Austin', 'New York', 'San Francisco'];
 2
 3foreach ($locations as $location) {
 4   doStuff();
 5   doSomeOtherStuff();
 6   // ...
 7   // ...
 8   // ...
 9   dispatch($location);
10}
  • 别添加没必要的上下文

如果你的类或对象的名字已经传达了一些信息，那么请别在变量名中重复。

不友好的

1class Car
2{
3   public $carMake;
4   public $carModel;
5   public $carColor;
6
7   //...
8}

友好的

1class Car
2{
3   public $make;
4   public $model;
5   public $color;
6
7   //...
8}
  • 用参数默认值代替短路运算或条件运算

不友好的

这里不太合理，因为变量$breweryName有可能是NULL。

1function createMicrobrewery($breweryName = 'Hipster Brew Co.'): void
2{
3   // ...
4}

不至于那么糟糕的

这种写法要比上一版稍微好理解一些，但是如果能控制变量值获取会更好。

1function createMicrobrewery($name = null): void
2{
3   $breweryName = $name ?: 'Hipster Brew Co.';
4   // ...
5}

友好的

如果你仅支持 PHP 7+，那么你可以使用类型约束并且保证$http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration变量不会为NULL。

1function createMicrobrewery(string $breweryName = 'Hipster Brew Co.'): void
2{
3   // ...
4}

函数

  • 函数参数应该控制在两个以下

限制函数的参数对于在对函数做测试来说相当重要。有超过三个可选的参数会给你的测试工作量带来倍速增长。

最理想的情况是没有参数。1-2个参数也还凑合，但是三个参数就应该避免了。参数越多，我们需要维护的就越多。通常，如果你的函>数有超过2个的参数，那么你的这个函数需要处理的事情就太多了。如果的确需要这么多参数，那么在大多数情况下， 用一个对象来处理可能会更合适。

不友好的:

1function createMenu(string $title, string $body, string $buttonText, bool $cancellable): void
2{
3   // ...
4}

友好的:

 1class MenuConfig
 2{
 3   public $title;
 4   public $body;
 5   public $buttonText;
 6   public $cancellable = false;
 7}
 8
 9$config = new MenuConfig();
10$config->title = 'Foo';
11$config->body = 'Bar';
12$config->buttonText = 'Baz';
13$config->cancellable = true;
14
15function createMenu(MenuConfig $config): void
16{
17   // ...
18}
  • 一个函数只做一件事情

在软件工程行业，这是最重要的准则。当函数所处理的事情超过一件，他就会变得难以实现，测试和理解。当你能让一个函数仅仅负责一个事情，他们就会变得容易重构并且理解起来越清晰。光是执行这样一条原则就能让你成为开发者中的佼佼者了。

不友好的:

1function emailClients(array $clients): void
2{
3   foreach ($clients as $client) {
4       $clientRecord = $db->find($client);
5       if ($clientRecord->isActive()) {
6           email($client);
7       }
8   }
9}

友好的:

 1function emailClients(array $clients): void
 2{
 3   $activeClients = activeClients($clients);
 4   array_walk($activeClients, 'email');
 5}
 6
 7function activeClients(array $clients): array
 8{
 9   return array_filter($clients, 'isClientActive');
10}
11
12function isClientActive(int $client): bool
13{
14   $clientRecord = $db->find($client);
15
16   return $clientRecord->isActive();
17}
  • 函数名应该说到做到

不友好的:

 1class Email
 2{
 3   //...
 4
 5   public function handle(): void
 6   {
 7       mail($this->to, $this->subject, $this->body);
 8   }
 9}
10
11$message = new Email(...);
12// 这是什么？这个`handle`方法是什么？我们现在应该写入到一个文件吗？
13$message->handle();

友好的:

 1class Email 
 2{
 3   //...
 4
 5   public function send(): void
 6   {
 7       mail($this->to, $this->subject, $this->body);
 8   }
 9}
10
11$message = new Email(...);
12// 清晰并且显而易见
13$message->send();
  • 函数应该只有一层抽象

当你的函数有超过一层的抽象时便意味着这个函数做了太多事情。解耦这个函数致使其变得可重用和更易测试。

不友好的:

 1function parseBetterJSAlternative(string $code): void
 2{
 3   $regexes = [
 4       // ...
 5   ];
 6
 7   $statements = explode(' ', $code);
 8   $tokens = [];
 9   foreach ($regexes as $regex) {
10       foreach ($statements as $statement) {
11           // ...
12       }
13   }
14
15   $ast = [];
16   foreach ($tokens as $token) {
17       // lex...
18   }
19
20   foreach ($ast as $node) {
21       // parse...
22   }
23}

同样不太友好:

我们已经从函数中拆分除了一些东西出来，但是parseBetterJSAlternative()这个函数还是太复杂以至于难以测试。

 1function tokenize(string $code): array
 2{
 3   $regexes = [
 4       // ...
 5   ];
 6
 7   $statements = explode(' ', $code);
 8   $tokens = [];
 9   foreach ($regexes as $regex) {
10       foreach ($statements as $statement) {
11           $tokens[] = /* ... */;
12       }
13   }
14
15   return $tokens;
16}
17
18function lexer(array $tokens): array
19{
20   $ast = [];
21   foreach ($tokens as $token) {
22       $ast[] = /* ... */;
23   }
24
25   return $ast;
26}
27
28function parseBetterJSAlternative(string $code): void
29{
30   $tokens = tokenize($code);
31   $ast = lexer($tokens);
32   foreach ($ast as $node) {
33       // parse...
34   }
35}

友好的

最优解就是把parseBetterJSAlternative()函数依赖的东西分离出来。

 1class Tokenizer
 2{
 3   public function tokenize(string $code): array
 4   {
 5       $regexes = [
 6           // ...
 7       ];
 8
 9       $statements = explode(' ', $code);
10       $tokens = [];
11       foreach ($regexes as $regex) {
12           foreach ($statements as $statement) {
13               $tokens[] = /* ... */;
14           }
15       }
16
17      return $tokens;
18   }
19}
20
21class Lexer
22{
23   public function lexify(array $tokens): array
24   {
25       $ast = [];
26       foreach ($tokens as $token) {
27           $ast[] = /* ... */;
28       }
29
30      return $ast;
31   }
32}
33
34class BetterJSAlternative
35{
36   private $tokenizer;
37   private $lexer;
38
39   public function __construct(Tokenizer $tokenizer, Lexer $lexer)
40   {
41       $this->tokenizer = $tokenizer;
42       $this->lexer = $lexer;
43   }
44
45   public function parse(string $code): void
46   {
47       $tokens = $this->tokenizer->tokenize($code);
48       $ast = $this->lexer->lexify($tokens);
49       foreach ($ast as $node) {
50           // parse...
51       }
52   }
53}
  • 不要在函数中带入flag相关的参数

当你使用flag时便意味着你的函数做了超过一件事情。前面我们也提到了，函数应该只做一件事情。如果你的代码取决于一个boolean，那么还是把这些内容拆分出来吧。

不友好的

1function createFile(string $name, bool $temp = false): void
2{
3   if ($temp) {
4       touch('./temp/'.$name);
5   } else {
6       touch($name);
7   }
8}

友好的

1function createFile(string $name): void
2{
3   touch($name);
4}
5
6function createTempFile(string $name): void
7{
8   touch('./temp/'.$name);
9}
  • 避免函数带来的副作用

当函数有数据的输入和输出时可能会产生副作用。这个副作用可能被写入一个文件，修改一些全局变量，或者意外的把你的钱转给一个陌生人。

此刻，你可能有时候会需要这些副作用。正如前面所说，你可能需要写入到一个文件中。你需要注意的是把这些你所做的东西在你的掌控之下。别让某些个别函数或者类写入了一个特别的文件。对于所有的都应该一视同仁。有且仅有一个结果。

重要的是要避免那些譬如共享无结构的对象，使用可以写入任何类型的可变数据，不对副作用进行集中处理等常见的陷阱。如果你可以做到，你将会比大多数程序猿更加轻松。

不友好的

 1// 全局变量被下面的函数引用了。
 2// 如果我们在另外一个函数中使用了这个`$name`变量，那么可能会变成一个数组或者程序被打断。
 3$name = 'Ryan McDermott';
 4
 5function splitIntoFirstAndLastName(): void
 6{
 7   global $name;
 8
 9   $name = explode(' ', $name);
10}
11
12splitIntoFirstAndLastName();
13
14var_dump($name); // ['Ryan', 'McDermott'];

友好的

 1function splitIntoFirstAndLastName(string $name): array
 2{
 3   return explode(' ', $name);
 4}
 5
 6$name = 'Ryan McDermott';
 7$newName = splitIntoFirstAndLastName($name);
 8
 9var_dump($name); // 'Ryan McDermott';
10var_dump($newName); // ['Ryan', 'McDermott'];
  • 避免写全局方法

在大多数语言中，全局变量被污染都是一个不太好的实践，因为当你引入另外的包时会起冲突并且使用你的API的人知道抛出了一个异常才明白。我们假设一个简单的例子：如果你想要一个配置数组。你可能会写一个类似于config()的全局的函数，但是在引入其他包并在其他地方尝试做同样的事情时会起冲突。

不友好的

1function config(): array
2{
3   return  [
4       'foo' => 'bar',
5   ]
6}

不友好的

 1class Configuration
 2{
 3   private $configuration = [];
 4
 5   public function __construct(array $configuration)
 6   {
 7       $this->configuration = $configuration;
 8   }
 9
10   public function get(string $key): ?string
11   {
12       return isset($this->configuration[$key]) ? $this->configuration[$key] : null;
13   }
14}

通过创建Configuration类的实例来引入配置

1$configuration = new Configuration([
2   'foo' => 'bar',
3]);

至此，你就可以是在你的项目中使用这个配置了。

  • 避免使用单例模式

单例模式是一种反模式。为什么不建议使用:

  1. 他们通常使用一个全局实例，为什么这么糟糕？因为你隐藏了依赖关系在你的项目的代码中，而不是通过接口暴露出来。你应该有意识的去避免那些全局的东西。
  2. 他们违背了单一职责原则：他们会自己控制自己的生命周期。
  3. 这种模式会自然而然的使代码耦合在一起。这会让他们在测试中，很多情况下都理所当然的不一致。
  4. 他们持续在整个项目的生命周期中。另外一个严重的打击是当你需要排序测试的时候，在单元测试中这会是一个不小的麻烦。为什么？因为每个单元测试都应该依赖于另外一个。

不友好的

 1class DBConnection
 2{
 3   private static $instance;
 4
 5   private function __construct(string $dsn)
 6   {
 7       // ...
 8   }
 9
10   public static function getInstance(): DBConnection
11   {
12       if (self::$instance === null) {
13           self::$instance = new self();
14       }
15
16       return self::$instance;
17   }
18
19   // ...
20}
21
22$singleton = DBConnection::getInstance();

友好的

1class DBConnection
2{
3   public function __construct(string $dsn)
4   {
5       // ...
6   }
7
8    // ...
9}

使用DSN配置来创建一个DBConnection类的单例。

1$connection = new DBConnection($dsn);

此时，在你的项目中必须使用DBConnection的单例。

  • 对条件判断进行包装

不友好的

1if ($article->state === 'published') {
2   // ...
3}

友好的

1if ($article->isPublished()) {
2   // ...
3}
  • 避免对条件取反

不友好的

1function isDOMNodeNotPresent(\DOMNode $node): bool
2{
3   // ...
4}
5
6if (!isDOMNodeNotPresent($node))
7{
8   // ...
9}

友好的

1function isDOMNodePresent(\DOMNode $node): bool
2{
3   // ...
4}
5
6if (isDOMNodePresent($node)) {
7   // ...
8}
  • 避免太多的条件嵌套

这似乎是一个不可能的任务。很多人的脑海中可能会在第一时间萦绕“如果没有if条件我还能做什么呢？”。答案就是，在大多数情况下，你可以使用多态去处理这个难题。此外，可能有人又会说了，“即使多态可以做到，但是我们为什么要这么做呢？”，对此我们的解释是，一个函数应该只做一件事情，这也正是我们在前面所提到的让代码更加整洁的原则。当你的函数中使用了太多的if条件时，便意味着你的函数做了超过一件事情。牢记：要专一。

不友好的:

 1class Airplane
 2{
 3   // ...
 4
 5   public function getCruisingAltitude(): int
 6   {
 7       switch ($this->type) {
 8           case '777':
 9               return $this->getMaxAltitude() - $this->getPassengerCount();
10           case 'Air Force One':
11               return $this->getMaxAltitude();
12           case 'Cessna':
13               return $this->getMaxAltitude() - $this->getFuelExpenditure();
14       }
15   }
16}

友好的:

 1interface Airplane
 2{
 3   // ...
 4
 5   public function getCruisingAltitude(): int;
 6}
 7
 8class Boeing777 implements Airplane
 9{
10   // ...
11
12   public function getCruisingAltitude(): int
13   {
14       return $this->getMaxAltitude() - $this->getPassengerCount();
15   }
16}
17
18class AirForceOne implements Airplane
19{
20   // ...
21
22   public function getCruisingAltitude(): int
23   {
24       return $this->getMaxAltitude();
25   }
26}
27
28class Cessna implements Airplane
29{
30   // ...
31
32   public function getCruisingAltitude(): int
33   {
34       return $this->getMaxAltitude() - $this->getFuelExpenditure();
35   }
36}
  • 避免类型检测 (part 1)

PHP是一门弱类型语言，这意味着你的函数可以使用任何类型的参数。他在给予你无限的自由的同时又让你困扰，因为有有时候你需要做类型检测。这里有很多方式去避免这种事情，第一种方式就是统一API。

不友好的：

1function travelToTexas($vehicle): void
2{
3   if ($vehicle instanceof Bicycle) {
4       $vehicle->pedalTo(new Location('texas'));
5   } elseif ($vehicle instanceof Car) {
6       $vehicle->driveTo(new Location('texas'));
7   }
8}

友好的：

1function travelToTexas(Traveler $vehicle): void
2{
3   $vehicle->travelTo(new Location('texas'));
4}
  • 避免类型检测 (part 2)

如果你正使用诸如字符串、整型和数组等基本类型，且要求版本是PHP 7+，不能使用多态，需要类型检测，那你应当考虑类型声明或者严格模式。它提供了基于标准PHP语法的静态类型。手动检查类型的问题是做好了需要好多的废话，好像为了安全就可以不顾损失可读性。保持你的PHP代码整洁，写好测试，保持良好的回顾代码的习惯。否则的话，那就还是用PHP严格类型声明和严格模式来确保安全吧。

不友好的:

1function combine($val1, $val2): int
2{
3   if (!is_numeric($val1) || !is_numeric($val2)) {
4       throw new \Exception('Must be of type Number');
5   }
6
7   return $val1 + $val2;
8}

友好的:

1function combine(int $val1, int $val2): int
2{
3   return $val1 + $val2;
4}
  • 移除那些没有使用的代码

没有再使用的代码就好比重复代码一样糟糕。在你的代码库中完全没有必要保留。如果确定不再使用，那就把它删掉吧！如果有一天你要使用，你也可以在你的版本记录中找到它。

不友好的:

 1function oldRequestModule(string $url): void
 2{
 3   // ...
 4}
 5
 6function newRequestModule(string $url): void
 7{
 8   // ...
 9}
10
11$request = newRequestModule($requestUrl);
12inventoryTracker('apples', $request, 'www.inventory-awesome.io');

友好的:

1function requestModule(string $url): void
2{
3   // ...
4}
5
6$request = requestModule($requestUrl);
7inventoryTracker('apples', $request, 'www.inventory-awesome.io');

对象和数据结构

  • 使用对象封装

在PHP中你可以设置public，protected，和private关键词来修饰你的方法。当你使用它们，你就可以在一个对象中控制这些属性的修改权限了。

  • 当你想要对对象的属性进行除了“获取”之外的操作时，你不必再去浏览并在代码库中修改权限。
  • 当你要做一些修改属性的操作时，你更易于在代码中做逻辑验证。
  • 封装内部表示。
  • 当你在做获取和设置属性的操作时，更易于添加log或error的操作。
  • 当其他class继承了这个基类，你可以重写默认的方法。
  • 你可以为一个服务延迟的去获取这个对象的属性值。

不太友好的:

1class BankAccount
2{
3   public $balance = 1000;
4}
5
6$bankAccount = new BankAccount();
7
8// Buy shoes...
9$bankAccount->balance -= 100;

友好的:

 1class BankAccount
 2{
 3   private $balance;
 4
 5   public function __construct(int $balance = 1000)
 6   {
 7     $this->balance = $balance;
 8   }
 9
10   public function withdraw(int $amount): void
11   {
12       if ($amount > $this->balance) {
13           throw new \Exception('Amount greater than available balance.');
14       }
15
16       $this->balance -= $amount;
17   }
18
19   public function deposit(int $amount): void
20   {
21       $this->balance += $amount;
22   }
23
24   public function getBalance(): int
25   {
26       return $this->balance;
27   }
28}
29
30$bankAccount = new BankAccount();
31
32// Buy shoes...
33$bankAccount->withdraw($shoesPrice);
34
35// Get balance
36$balance = $bankAccount->getBalance();
  • 在对象的属性上可以使用private/protected限定
  • public修饰的方法和属性同上来说被修改是比较危险的，因为一些外部的代码可以轻易的依赖于他们并且你没办法控制哪些代码依赖于他们。对于所有用户的类来说，在类中可以修改是相当危险的。
  • protected修饰器和public同样危险，因为他们在继承链中同样可以操作。二者的区别仅限于权限机制，并且封装保持不变。对于所有子类来说，在类中修改也是相当危险的。
  • private修饰符保证了代码只有在自己类的内部修改才是危险的。

因此，当你在需要对外部的类设置权限时使用private修饰符去取代public/protected吧。

如果需要了解更多信息你可以读Fabien Potencier写的这篇文章

不太友好的:

 1class Employee
 2{
 3   public $name;
 4
 5   public function __construct(string $name)
 6   {
 7       $this->name = $name;
 8   }
 9}
10
11$employee = new Employee('John Doe');
12echo 'Employee name: '.$employee->name; // Employee name: John Doe

友好的:

 1class Employee
 2{
 3   private $name;
 4
 5   public function __construct(string $name)
 6   {
 7       $this->name = $name;
 8   }
 9
10   public function getName(): string
11   {
12       return $this->name;
13   }
14}
15
16$employee = new Employee('John Doe');
17echo 'Employee name: '.$employee->getName(); // Employee name: John Doe
  • 组合优于继承

正如the Gang of Four在著名的Design Patterns中所说，你应该尽可能的使用组合而不是继承。不管是使用组合还是继承都有很多的优点。最重要的一个准则在于当你本能的想要使用继承时，不妨思考一下组合是否能让你的问题解决的更加优雅。在某些时候确实如此。

你可能会这么问了，“那到底什么时候我应该使用继承呢？”这完全取决你你手头上的问题，下面正好有一些继承优于组合的例子：

  1. 你的继承表达了“是一个”而不是“有一个”的关系(Human->Animal vs. User->UserDetails)。
  2. 你可能会重复的使用基类的代码(Humans can move like all animals)。
  3. 你渴望在修改代码的时候通过基类来统一调度(Change the caloric expenditure of all animals when they move)。

不友好的:

 1class Employee 
 2{
 3   private $name;
 4   private $email;
 5
 6   public function __construct(string $name, string $email)
 7   {
 8       $this->name = $name;
 9       $this->email = $email;
10   }
11
12   // ...
13}
14
15// 这里不太合理的原因在于并非所有的职员都有`tax`这个特征。
16
17class EmployeeTaxData extends Employee 
18{
19   private $ssn;
20   private $salary;
21  
22   public function __construct(string $name, string $email, string $ssn, string $salary)
23   {
24       parent::__construct($name, $email);
25
26       $this->ssn = $ssn;
27       $this->salary = $salary;
28   }
29
30   // ...
31}

友好的:

 1class EmployeeTaxData 
 2{
 3   private $ssn;
 4   private $salary;
 5
 6   public function __construct(string $ssn, string $salary)
 7   {
 8       $this->ssn = $ssn;
 9       $this->salary = $salary;
10   }
11
12   // ...
13}
14
15class Employee 
16{
17   private $name;
18   private $email;
19   private $taxData;
20
21   public function __construct(string $name, string $email)
22   {
23       $this->name = $name;
24       $this->email = $email;
25   }
26
27   public function setTaxData(string $ssn, string $salary)
28   {
29       $this->taxData = new EmployeeTaxData($ssn, $salary);
30   }
31
32   // ...
33}
  • 避免链式调用(连贯接口)

在使用一些链式方法时，这种连贯接口可以不断地指向当前对象让我们的代码显得更加清晰可读。

通常情况下，我们在构建对象时都可以利用他的上下文这一特征，因为这种模式可以减少代码的冗余，不过在[PHPUnit Mock Builder]((https://phpunit.de/manual/current/en/test-doubles.html)或者Doctrine Query Builder所提及的，有时候这种方式会带来一些麻烦：

  1. 破坏封装
  2. 破坏设计
  3. 难以测试
  4. 可能会难以阅读

如果需要了解更多信息你可以读Marco Pivetta写的这篇文章

友好的:

 1class Car
 2{
 3   private $make = 'Honda';
 4   private $model = 'Accord';
 5   private $color = 'white';
 6
 7   public function setMake(string $make): self
 8   {
 9       $this->make = $make;
10
11       // NOTE: Returning this for chaining
12       return $this;
13   }
14
15   public function setModel(string $model): self
16   {
17       $this->model = $model;
18
19       // NOTE: Returning this for chaining
20       return $this;
21   }
22
23   public function setColor(string $color): self
24   {
25       $this->color = $color;
26
27       // NOTE: Returning this for chaining
28       return $this;
29   }
30
31   public function dump(): void
32   {
33       var_dump($this->make, $this->model, $this->color);
34   }
35}
36
37$car = (new Car())
38 ->setColor('pink')
39 ->setMake('Ford')
40 ->setModel('F-150')
41 ->dump();

不友好的:

 1class Car
 2{
 3   private $make = 'Honda';
 4   private $model = 'Accord';
 5   private $color = 'white';
 6
 7   public function setMake(string $make): void
 8   {
 9       $this->make = $make;
10   }
11
12   public function setModel(string $model): void
13  {
14       $this->model = $model;
15   }
16
17   public function setColor(string $color): void
18   {
19       $this->color = $color;
20   }
21
22   public function dump(): void
23   {
24       var_dump($this->make, $this->model, $this->color);
25   }
26}
27
28$car = new Car();
29$car->setColor('pink');
30$car->setMake('Ford');
31$car->setModel('F-150');
32$car->dump();

SOLID

SOLID最开始是由Robert Martin提出的五个准则，并最后由Michael Feathers命名的简写，这五个是在面对对象设计中的五个基本原则。

  • S: 职责单一原则 (SRP)
  • O: 开闭原则 (OCP)
  • L: 里氏替换原则 (LSP)
  • I: 接口隔离原则 (ISP)
  • D: 依赖反转原则 (DIP)
  • 职责单一原则 (SRP)

正如Clean Code所述，“修改类应该只有一个理由”。我们总是喜欢在类中写入太多的方法，就像你在飞机上塞满你的行李箱。在这种情况下你的类没有高内聚的概念并且留下了很多可以修改的理由。尽可能的减少你需要去修改类的时间是非常重要的。如果在你的单个类中有太多的方法并且你经常修改的话，那么如果其他代码库中有引入这样的模块的话会非常难以理解。

不友好的:

 1class UserSettings
 2{
 3   private $user;
 4
 5   public function __construct(User $user)
 6   {
 7       $this->user = $user;
 8   }
 9
10   public function changeSettings(array $settings): void
11   {
12       if ($this->verifyCredentials()) {
13           // ...
14       }
15   }
16
17   private function verifyCredentials(): bool
18   {
19       // ...
20   }
21}

友好的:

 1class UserAuth 
 2{
 3   private $user;
 4
 5   public function __construct(User $user)
 6   {
 7       $this->user = $user;
 8   }
 9 
10   public function verifyCredentials(): bool
11   {
12       // ...
13   }
14}
15
16class UserSettings 
17{
18   private $user;
19   private $auth;
20
21   public function __construct(User $user) 
22   {
23       $this->user = $user;
24       $this->auth = new UserAuth($user);
25   }
26
27   public function changeSettings(array $settings): void
28   {
29       if ($this->auth->verifyCredentials()) {
30           // ...
31       }
32   }
33}
  • 开闭原则 (OCP)

正如Bertrand Meyer所说，“软件开发应该对扩展开发，对修改关闭。”这是什么意思呢？这个原则的意思大概就是说你应该允许其他人在不修改已经存在的功能的情况下去增加新功能。

不友好的

 1abstract class Adapter
 2{
 3   protected $name;
 4
 5   public function getName(): string
 6   {
 7       return $this->name;
 8   }
 9}
10
11class AjaxAdapter extends Adapter
12{
13   public function __construct()
14   {
15      parent::__construct();
16
17       $this->name = 'ajaxAdapter';
18   }
19}
20
21class NodeAdapter extends Adapter
22{
23   public function __construct()
24   {
25       parent::__construct();
26
27       $this->name = 'nodeAdapter';
28   }
29}
30
31class HttpRequester
32{
33   private $adapter;
34
35   public function __construct(Adapter $adapter)
36   {
37       $this->adapter = $adapter;
38   }
39
40   public function fetch(string $url): Promise
41   {
42       $adapterName = $this->adapter->getName();
43
44       if ($adapterName === 'ajaxAdapter') {
45           return $this->makeAjaxCall($url);
46       } elseif ($adapterName === 'httpNodeAdapter') {
47           return $this->makeHttpCall($url);
48       }
49   }
50
51   private function makeAjaxCall(string $url): Promise
52   {
53       // request and return promise
54   }
55
56   private function makeHttpCall(string $url): Promise
57   {
58       // request and return promise
59   }
60}

友好的:

 1interface Adapter
 2{
 3   public function request(string $url): Promise;
 4}
 5
 6class AjaxAdapter implements Adapter
 7{
 8   public function request(string $url): Promise
 9   {
10       // request and return promise
11   }
12}
13
14class NodeAdapter implements Adapter
15{
16   public function request(string $url): Promise
17   {
18       // request and return promise
19   }
20}
21
22class HttpRequester
23{
24   private $adapter;
25
26   public function __construct(Adapter $adapter)
27   {
28       $this->adapter = $adapter;
29   }
30
31   public function fetch(string $url): Promise
32   {
33       return $this->adapter->request($url);
34   }
35}
  • 里氏替换原则 (LSP)

这本身是一个非常简单的原则却起了一个不太容易理解的名字。这个原则通常的定义是“如果S是T的一个子类，那么对象T可以在没有任何警告的情况下被他的子类替换（例如：对象S可能代替对象T）一些更合适的属性。”好像更难理解了。

最好的解释就是说如果你有一个父类和子类，那么你的父类和子类可以在原来的基础上任意交换。这个可能还是难以理解，我们举一个正方形-长方形的例子吧。在数学中，一个矩形属于长方形，但是如果在你的模型中通过继承使用了“is-a”的关系就不对了。

不友好的:

 1class Rectangle
 2{
 3   protected $width = 0;
 4   protected $height = 0;
 5
 6   public function render(int $area): void
 7   {
 8       // ...
 9   }
10
11   public function setWidth(int $width): void
12   {
13       $this->width = $width;
14   }
15
16   public function setHeight(int $height): void
17   {
18       $this->height = $height;
19   }
20
21   public function getArea(): int
22   {
23      return $this->width * $this->height;
24   }
25}
26
27class Square extends Rectangle
28{
29   public function setWidth(int $width): void
30   {
31       $this->width = $this->height = $width;
32   }
33
34   public function setHeight(int $height): void
35   {
36       $this->width = $this->height = $height;
37   }
38}
39
40function renderLargeRectangles(array $rectangles): void
41{
42   foreach ($rectangles as $rectangle) {
43       $rectangle->setWidth(4);
44       $rectangle->setHeight(5);
45       $area = $rectangle->getArea(); // BAD: Will return 25 for Square. Should be 20.
46       $rectangle->render($area);
47   }
48}
49
50$rectangles = [new Rectangle(), new Rectangle(), new Square()];
51renderLargeRectangles($rectangles);

友好的:

 1abstract class Shape
 2{
 3   protected $width = 0;
 4   protected $height = 0;
 5
 6   abstract public function getArea(): int;
 7
 8   public function render(int $area): void
 9  {
10       // ...
11   }
12}
13
14class Rectangle extends Shape
15{
16   public function setWidth(int $width): void
17   {
18       $this->width = $width;
19   }
20
21   public function setHeight(int $height): void
22   {
23       $this->height = $height;
24   }
25
26   public function getArea(): int
27   {
28       return $this->width * $this->height;
29   }
30}
31
32class Square extends Shape
33{
34   private $length = 0;
35
36   public function setLength(int $length): void
37   {
38       $this->length = $length;
39   }
40
41   public function getArea(): int
42   {
43       return pow($this->length, 2);
44   }
45}
46
47
48function renderLargeRectangles(array $rectangles): void
49{
50   foreach ($rectangles as $rectangle) {
51       if ($rectangle instanceof Square) {
52           $rectangle->setLength(5);
53       } elseif ($rectangle instanceof Rectangle) {
54           $rectangle->setWidth(4);
55           $rectangle->setHeight(5);
56       }
57
58       $area = $rectangle->getArea(); 
59       $rectangle->render($area);
60   }
61}
62
63$shapes = [new Rectangle(), new Rectangle(), new Square()];
64renderLargeRectangles($shapes);
  • 接口隔离原则 (ISP)

ISP的意思就是说“使用者不应该强制使用它不需要的接口”。

当一个类需要大量的设置是一个不错的例子去解释这个原则。为了方便去调用这个接口需要做大量的设置，但是大多数情况下是不需要的。强制让他们使用这些设置会让整个接口显得臃肿。

不友好的:

 1interface Employee
 2{
 3   public function work(): void;
 4
 5   public function eat(): void;
 6}
 7
 8class Human implements Employee
 9{
10   public function work(): void
11   {
12       // ....working
13   }
14
15   public function eat(): void
16   {
17       // ...... eating in lunch break
18   }
19}
20
21class Robot implements Employee
22{
23   public function work(): void
24   {
25       //.... working much more
26   }
27
28   public function eat(): void
29   {
30       //.... robot can't eat, but it must implement this method
31   }
32}

友好的:

并非每一个工人都是职员，但是每一个职员都是工人。

 1interface Workable
 2{
 3   public function work(): void;
 4}
 5
 6interface Feedable
 7{
 8   public function eat(): void;
 9}
10
11interface Employee extends Feedable, Workable
12{
13}
14
15class Human implements Employee
16{
17   public function work(): void
18   {
19       // ....working
20   }
21
22   public function eat(): void
23   {
24       //.... eating in lunch break
25   }
26}
27
28// robot can only work
29class Robot implements Workable
30{
31   public function work(): void
32   {
33       // ....working
34   }
35}
  • 依赖反转原则 (DIP)

这个原则有两个需要注意的地方：

  1. 高阶模块不能依赖于低阶模块。他们都应该依赖于抽象。
  2. 抽象不应该依赖于实现，实现应该依赖于抽象。

第一点可能有点难以理解，但是如果你有使用过像Symfony的PHP框架，你应该有见到过依赖注入这样的原则的实现。尽管他们是不一样的概念，DIP让高阶模块从我们所知道的低阶模块中分离出去。可以通过DI这种方式实现。一个巨大的好处在于它解耦了不同的模块。耦合是一个非常不好的开发模式，因为它会让你的代码难以重构。

不友好的:

 1class Employee
 2{
 3   public function work(): void
 4   {
 5       // ....working
 6   }
 7}
 8
 9class Robot extends Employee
10{
11   public function work(): void
12   {
13       //.... working much more
14   }
15}
16
17class Manager
18{
19   private $employee;
20
21   public function __construct(Employee $employee)
22   {
23       $this->employee = $employee;
24   }
25
26   public function manage(): void
27   {
28       $this->employee->work();
29   }
30}

友好的

 1interface Employee
 2{
 3   public function work(): void;
 4}
 5
 6class Human implements Employee
 7{
 8   public function work(): void
 9   {
10       // ....working
11   }
12}
13
14class Robot implements Employee
15{
16   public function work(): void
17   {
18       //.... working much more
19   }
20}
21
22class Manager
23{
24   private $employee;
25
26   public function __construct(Employee $employee)
27   {
28       $this->employee = $employee;
29   }
30
31   public function manage(): void
32   {
33       $this->employee->work();
34   }
35}

别重复你的代码 (DRY)

尝试去研究DRY原则。

尽可能别去复制代码。复制代码非常不好，因为这意味着将来有需要修改的业务逻辑时你需要修改不止一处。

想象一下你在经营一个餐馆并且你需要经常整理你的存货清单：你所有的土豆，洋葱，大蒜，辣椒等。如果你有多个列表来管理进销记录，当你用其中一些土豆做菜时你需要更新所有的列表。如果你只有一个列表的话只有一个地方需要更新!

大多数情况下你有重复的代码是因为你有超过两处细微的差别，他们大部分都是相同的，但是他们的不同之处又不得不让你去分成不同的方法去处理相同的事情。移除这些重复的代码意味着你需要创建一个可以用一个方法/模块/类来处理的抽象。

使用一个抽象是关键的，这也是为什么在类中你要遵循SOLID原则的原因。一个不优雅的抽象往往比重复的代码更糟糕，所以要谨慎使用！说了这么多，如果你已经可以构造一个优雅的抽象，那就赶紧去做吧！别重复你的代码，否则当你需要修改时你会发现你要修改许多地方。

不友好的:

 1function showDeveloperList(array $developers): void
 2{
 3   foreach ($developers as $developer) {
 4       $expectedSalary = $developer->calculateExpectedSalary();
 5       $experience = $developer->getExperience();
 6       $githubLink = $developer->getGithubLink();
 7       $data = [
 8           $expectedSalary,
 9           $experience,
10           $githubLink
11       ];
12
13       render($data);
14   }
15}
16
17function showManagerList(array $managers): void
18{
19   foreach ($managers as $manager) {
20       $expectedSalary = $manager->calculateExpectedSalary();
21       $experience = $manager->getExperience();
22       $githubLink = $manager->getGithubLink();
23       $data = [
24           $expectedSalary,
25           $experience,
26           $githubLink
27       ];
28
29       render($data);
30   }
31}

友好的:

 1function showList(array $employees): void
 2{
 3   foreach ($employees as $employee) {
 4       $expectedSalary = $employee->calculateExpectedSalary();
 5       $experience = $employee->getExperience();
 6       $githubLink = $employee->getGithubLink();
 7       $data = [
 8           $expectedSalary,
 9           $experience,
10           $githubLink
11       ];
12
13       render($data);
14   }
15}

非常优雅的:

如果能更简洁那就更好了。

 1function showList(array $employees): void
 2{
 3   foreach ($employees as $employee) {
 4       render([
 5           $employee->calculateExpectedSalary(),
 6           $employee->getExperience(),
 7           $employee->getGithubLink()
 8       ]);
 9   }
10}

原文地址

clean-code-php

文章首发地址：我的博客