编写高可读性代码

人们总是被告知在代码中增加注释是很重要的。如果没有注释，其他开发人员将无法理解我们所做的事情，而我们在未来进行维护时也会感到迷茫。

但是，可读代码不仅涉及注释文本。更重要的是，它涉及样式、结构和命名。如果您习惯于编写易于阅读的代码，那么实际上您会发现自己编写的注释是很少的。

让我们对下面的代码片段进行优化以提高可读性。

<?php

// data
$a = [
    ['n'=>'John Smith', 'dob'=>'1988-02-03'],
    ['n'=>'Jane Jones', 'dob'=>'2014-07-08']
];

// iterate the array
for($x=0;$x<sizeof($a);$x++){/*calculate difference*/$a[$x]['a']=(new DateTime())->diff(new DateTime($a[$x]['dob']))->format("%y");}

这个简洁而混乱的代码是以年为单位计算数组中每个用户记录的使用期限。然后将年龄添加到数组的记录中备用。

那么，如何优化这段代码？

样式

第一步是修改代码样式。样式可能因项目而异，但应该始终包含有关缩进和间距的规则。

如果您要开始一个新项目或重构代码，建议您使用通用的标准。对于 PHP 而言，最知名的标准是 PSR-1 和 PSR-2。

这是代码缩进并使其适合最大 80 个字符的行之后的样子。

<?php
// iterate the array
for($x=0; $x<sizeof($a); $x++) {
    // calculate difference
    $a[$x]['a'] =
        (new DateTime())->diff(new DateTime($a[$x]['dob']))->format("%y");
}

如您所见，该代码的可读性提高了，并且还具有易于编辑的附加好处。

结构

代码结构包括从存储源的目录树到所使用的的方法和库的所有内容。在可读性方面，重要的因素是抽象、选择控制结构、数据结构和使用临时变量。

在这种情况下，重构结构意味着将 for 循环改为 foreach 循环，并将年龄计算分为几个步骤。foreach 循环中的值已设置为通过引用分配，以便在更改值时更新数组。

<?php
// iterate the array
foreach($a as &$u) {    
    // calculate difference
    $t = new DateTime();
    $b = new DateTime($u['dob']);
    $d = $t->diff($b);
    $u['a'] = $d->format("%y");
}
unset($u);

现在，我们可以轻松地看到年龄计算中所涉及的各个步骤以及将结果存储在数组中的位置。使用 foreach 循环，在访问用户记录时不需要使用额外的计数器变量。

另一个方法是创建一个函数或方法来执行年龄计算。特别是在一个较大的项目中，需要在多个地方计算年龄。

命名

您肯定听过「自我记录代码」这一词。到目前为止，最重要的因素是为变量和数据结构命名。

永远不要担心使用更长的名称来提高可读性。 优秀的文本编辑器和 IDE 都具有补全功能，因此较长的名称不会减慢您的速度。现代编程语言和数据库支持 50 个或更多字符的名称。与名称的上下文（表、名称空间、类等）相结合，有足够的空间容纳有意义的名称。

在我们的示例中，可以通过使用反映其内容的名称来改进用户记录使用的变量名称和键。记住要对所有其他命名（包括函数，类，属性和方法）应用相同的思想。

<?php

// data
$users = [
    ['name'=>'John Smith', 'birthday'=>'1988-02-03'],
    ['name'=>'Jane Jones', 'birthday'=>'2014-07-08']
];

// iterate the array
foreach($users as &$user) { 
    // calculate difference
    $today = new DateTime();
    $birthday = new DateTime($user['birthday']);
    $age = $today->diff($birthday);
    $user['age'] = $age->format("%y");
}
unset($user);

现在，代码的目的更加容易理解了，因为我们可以一目了然地看到每个变量中包含的内容。

注释

注释应使用高级术语说明代码的预期结果。永远不要用低级术语来执行代码。他们还应该记录任何可能不太明显的副作用。

在这种情况下，只需一个注释即可指定 foreach 循环正在执行的操作。users 数组的注释已删除，因为现在可以轻松查看该数组的用途。

<?php

$users = [
    ['name'=>'John Smith', 'birthday'=>'1988-02-03'],
    ['name'=>'Jane Jones', 'birthday'=>'2014-07-08']
];

// Calculate and store the age in years of each user
foreach($users as &$user) { 
    $today = new DateTime();
    $birthday = new DateTime($user['birthday']);
    $age = $today->diff($birthday);
    $user['age'] = $age->format("%y");
}
unset($user);

与初始代码进行比较，看看它是否更容易理解。

如果您发现自己编写的代码更像是早期迭代之一，请花一些时间来更正它。随着代码库的增长，这项投资将获得许多倍的回报。也考虑在重构现有代码上花费时间。

稍加练习和周到的准备，您将立即编写高度可读的代码。

编辑：Ryan Winchester 已更进一步采用此代码，并取消了所有的注释。另请参阅下方的 David Rosa 的回应，以了解不同的样式。

编辑：Freek Van der Herten 采取了 Ryan Winchester 的代码并重构了。

本文中的所有译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://medium.com/swlh/writing-highly-r...

译文地址：https://learnku.com/php/t/39290