编码标准第2部分：.EditorConfig，文档和严格类型-DEV365 开发者社区

在previous article中，我们已经学到了很多有关编码标准的知识，今天我想讨论另外三点：文件 .editorconfig ，您的代码文档和声明严格类型。

文件.editorConfig

.editorConfig 文件是您在插件的根文件夹中创建的文本文件。该文件可确保您和您的团队在整个项目中使用相同的标准进行线路断开，压痕和角色集。像Visual Studio Code这样的编辑可以读取此文件并自动应用格式和设置。 Visual Studio Code为此目的需要this extension。

Visual Studio代码的扩展名支持以下设置：

indent_style：凹痕样式：空格或标签
indent_size：使用空间时的缩进尺寸（软标签）
tab_width：使用标签时的缩进尺寸
end_of_line（保存时应用）：线断裂的类型
insert_final_newline（保存时应用）：指定是否应将空行添加到文件末尾（请参阅PSR-2）
trim_trailing_whitespace（保存时应用）：在实际代码行之后删除任何空格

在 .editorconfig 中，您可以为每个编程语言或文件扩展名设置样式。

我的文件通常看起来像这样：

# http://editorconfig.org

root = true

[*]
charset = utf-8
end_of_line = lf
indent_size = 2
indent_style = space
trim_trailing_whitespace = true

[*.php]
indent_size = 4
insert_final_newline = true

[*.scss]
insert_final_newline = true

[*.md]
trim_trailing_whitespace = false

使用root = true，可以指定该文件位于插件的根目录中。像VS代码这样的文本编辑器最初在当前打开的代码文件的文件夹中搜索A .editorConfig 文件。如果找不到，它将搜索上面的一个文件夹，依此类推。 LINE root = true表示搜索可以在此处结束，并且可以使用该文件。

使用[*]下的声明，进行了一般设置，并且在特定文件扩展程序的设置下方被覆盖。例如

即使您在团队中不工作，我建议使用 .editorConfig 文件。这样可以确保您在每个项目和每个设备上都使用相同的样式。

更多信息：editorconfig.org。

文档

受到许多开发人员的讨厌，它仍然是您和您的团队的重要工具。我想在这里强调，单独开发插件时，记录您的代码也很重要。我保证，当您必须在两到三个月后再次浏览代码时，您会喜欢您的文档！代码很快就变得遥远了，仅几个月后，您会记住特定的细节，例如为什么您以特定方式实现某些内容而不会有不同。

在文档方面，我们通常会区分两种类型的文档：

代码本身中的文档。
外部文档。

代码中的文档

在PHP中，我们不仅可以通过以下形式区分以前的双重斜杠（//）和多行文档：

/* This is a comment, 
   that spans
   over multiple lines
*/

我们还区分文件，类和功能/方法级别的文档。我建议在phpDocumentor中使用的PHPDoc format记录。 phpdoc块不是从/*开始，而是两个星号符号：/**。诸如Visual Studio Code之类的文本编辑器在键入/**时可以快速创建这些块，从而减少键入工作。

这是各种文档块的示例。

<?php

/**
 * At the very top appears the file-level documentation. Here you can discuss
 * what exactly is happening in this file. As with all documentation:
 * 
 * Document as much as necessary and as little as possible!
 * 
 * What this means, you can read further below.
 * 
 * Here you can, for example, specify the author and the version with which
 * this file was created:
 * 
 * @author: Marcus Kober
 * @since: 1.2.1
 */ 

declare(strict_types=1);

namespace MK\Test\Main;

use MK\Test\Attributes\Filter;

/**
 * DocBlock at the class level
 * 
 * The DocBlock is created directly before the class to be documented and indicates
 * what the class is for.
 */
class Frontend
{
    /**
     * DocBlock at the variable level
     * 
     * Here you can explain what this variable does
     *
     * @var array
     */
    protected array $addedClasses = [];

    /**
     * DocBlock at the method level
     * 
     * Here you can explain what the method does.
     * 
     * The DocBlock comes before the declaration of attributes, if
     * any are used.
     *
     * @param array $classes
     * @return array
     */
    #[Filter('body_class')]
    public function addClass(array $classes): array
    {
        // Single-line comment, very briefly, explaining something specific
        $this->addedClasses[] = 'my-class';

        return array_merge($classes, $this->addedClasses);
    }
}

以@开头的语句，例如@author或@since，称为Docblock语法的标签。在这里，您可以找到可能的标签列表。对于变量和方法，您可以使用@var或@param和@return指定类型。

使用放映的代码评论您的代码不仅会使您和团队更透明您的代码。您也可以使用PhpDocumentor从足够有据可查的代码中创建external API documentation。可以将其添加到您的外部文档（如果需要的话）中，甚至更换。

外部文档

对于非常广泛的插件，您可以公开或仅为自己和/或您的团队创建外部文档。外部文档发生在您的代码之外，例如在网站上，或者您可以使用为其设计的服务，例如GitBook或Read the Docs。

外部文档对于记录自己的钩子特别重要。还有一个有趣的项目自动记录您的钩子：Pronamic WordPress Documentor。它会自动从挂钩声明中以各种格式生成文档。您可以在即将发表的有关挂钩驱动开发的文章中找到有关挂钩的更多信息。

声明严格的类型

尽管由于空间限制，在本系列的早期文章中的大多数示例中都缺少相应的声明，但我强烈建议启用PHP严格类型检查。

声明是用declare(strict_types=1)进行的。这应该在插件的每个文件中完成，并且必须是这样确保您从根本上激活严格类型检查的方式。 declare语句立即在文件开头和名称空间声明之前放置：

<?php

declare(strict_types=1);

namespace MKMyPlugin;

// use statements

// ...

也请参考：PSR-12: Declare Statements, Namespace, and Import Statements

声明（strict_types = 1）准确地做什么？

语句declare(strict_types=1)在PHP中启用严格的类型检查。这导致了改善的代码质量和稳定性，因为使用严格的类型检查允许在文本编辑器中更快地检测到错误。

。

这检查了所谓的标量类型，即int，float，string和bool。

让我们以以下功能为例：

function add(float $a, float $b): float
{
    return $a + $b;
}

而无需启用严格的类型检查，我们可以在没有任何问题和错误消息的情况下运行以下内容：

echo add('1.2', 2.4);
// -> 3.6

php默默地将string('1.2')转换为float(1.2)，然后返回计算的float(3.6)。

由于这是可能难以找到的错误源，因此我们启用严格的类型使用declare(strict_types=1)在每个PHP文件中检查。

让我们在示例中看到这一点：

<?php

declare(strict_types=1);

function add(float $a, float $b): float
{
    return $a + $b;
}

echo add('1.2', 2.4);

这导致以下错误：

Fatal error: Uncaught TypeError: Argument 2 passed to add() must be of the type float, string given

当然，这也适用于返回值：

<?php

declare(strict_types=1);

function add(float $a, float $b): float
{
    return (string) $a + $b;
}

echo add(1.2, 2.4);

在这里，我们正确地将两个浮子传递到add()功能。但是，由于启用了返回类型的提示，并且我们指定该函数应返回float，但同时又将添加结果归为string，我们将遇到以下错误消息：

Fatal error: Uncaught TypeError: Return value of add() must be of the type float, string returned

重要：为了正确使用类型检查，您的功能和方法当然必须使用类型提示！类型提示指的是类型声明，例如，在上述函数声明中所见。在那里，我们明确地告诉$a和$b它们应该是类型的float，我们指出函数表明返回值也应为类型float：

function add(float $a, float $b): float

我强烈建议将插件的所有PHP文件与declare(strict_type=1)！

装备

结论

在本文中，您了解了三种方法，使代码更清洁，更可维护。两种方法涉及代码的外部形式（ .editorConfig 和文档），一种具有实际代码的质量和安全性（严格类型）。