保持整洁：重要的编码标准

一年前，我参与了一个项目，这个项目教会了我如何保持代码简洁、模块化、可复用，以及所有这些看似花哨但实际上对长远有益的术语。有趣吗？是的，有点意思。

但是我开始这些做法之后做了什么呢？

我犯过错误。相信我，我犯过很多错误。但每一次犯错，我都学到了很多以前从未考虑过的东西。它帮助我思考如何构建，以及在开发/扩展功能时需要考虑哪些步骤。最重要的是，这些经验不仅对我本人有帮助，对团队成长也至关重要。

起初，我们常常感到沮丧，因为必须遵循一些额外的流程，比如添加文档、维护变更日志文件、遵循代码标准，并在整个团队中保持一致。这些额外的步骤看起来很繁琐，我们无法理解这对我们（团队）有什么用处。我们在这方面仍然每天都在学习和改进。但几个月后，我们开始喜欢上并改进了这个过程。

所以，我在这里，分享我所学到的知识。相信我，一旦付诸实践，你就离不开它了。

这篇文章主要关注我们每天遵循哪些做法来让我们的生活更轻松（更多地关注 PHP/Drupal，但可以遵循，我们遵循非常通用的做法）。

让我们从简单的事情开始：

评论和文档标准

评论并不意味着在编码时随处添加一堆注释和随机文档。有些事情你应该提及，这样可以让同事和你自己的工作更轻松。

• 首先写下你的组件的描述，你为什么要创建它，以及你想在这里实现的目标是什么，它的作用是什么等等。
• 如果有修改，则应通过创建 Changelog.md 文件并将其附加到组件来记录。请保持特定格式以保持一致性。

这是我们遵循的，希望这很清楚：
CHANGELOG.md 文件示例：

• 添加@see引用该类是一种很好的做法，这将有助于使用 PHPStorm 等 IDE 或 Sublime 等编辑器只需单击一下即可轻松导航到该类定义。

• 必要时添加 @TODOS。如果你觉得你的代码将来可以改进，并且已经有了改进的想法，但目前时间不够，那么 @TODOS 就非常重要。请在代码片段上方提及需要改进的地方。一个很好的例子是：

• 创建 README.md 文件，以便其他人轻松了解模块的工作原理。例如：

• “Docblock” 是一种特殊的代码注释，它对代码块的目的、参数、返回值和抛出异常进行解释。

我在一条简单的推文中发现了一些非常有用的信息：

格式化

这可能包括缩进、空格、括号位置和换行符，并且根据不同的语言，这些设置可能有所不同。在我们的例子中，这些设置是针对 PHP（Drupal）的。编辑器中有很多插件可以用来美化你的代码。

命名约定

• 当然，命名规范取决于你使用的语言（例如：Zend，以及 Google 的 PHP、CSS、JavaScript、Java 等风格指南），但核心思想是使用描述性强且有意义的词语。因此，你应该避免使用 xx、yy2、test1、test2 等这样的变量命名规范。
• 例如，PHP 变量和函数使用 lower_case，JS 变量和函数使用 camelCase，CSS ID 和类使用 lower-case-hyphenated，常量使用 UPPER_CASE。
• 我们应该以一种能够轻松解释变量所含数据类型的方式命名变量。同样，对于函数，它们应该描述其提供的功能类型。这被称为自文档化代码。函数应该说明它们做什么，而不是如何做。这被称为抽象，它允许在不更改函数名称的情况下更改底层实现。

可移植性

尽可能保持代码松耦合。“可移植”是指将代码从一个平台迁移到另一个平台所需的工作量很少。在编写代码时，我们应该注意以下几点：

• 避免使用硬编码值，如绝对文件路径、URL 等，除非事关生死 (:P)
• 避免在代码中使用魔法数字。魔法数字本质上是一个硬编码的值，可能会在后期发生变化，因此很难更新。几乎所有除 0、1 或 2 之外的数字都应该在文件顶部赋值给一个常量。这样，当值发生变化时，只需一个更改点即可，而不是进行搜索替换，因为这可能会影响多个文件并可能引入错误。

棉绒

市面上有不同类型的工具可以用来查找语法差异，尤其是在 JavaScript、PHP、Python 等解释型语言中。它们也可以用作简单的调试器来查找常见错误。以下是一些常见的 linters：

• PHP：

  • 我们使用与 Drupal 集成的 PHP 代码嗅探器。您可以轻松使用您的编辑器（例如 Sublime）进行配置，它会在保存时显示常见的 PHP 错误，从而节省大量时间并在提交更改之前避免错误。

• JavaScript：

  • 我们有 Drupal JavaScript 编码标准（注意 - 这些标准与 Mavericks 标准在几个方面有所不同），但我们使用JSHint来列出与 JS 相关的代码检查。
  • 无论 Drupal 的 JS 格式约定与 JSHint 发生什么冲突，JSHint 都会取代它。

• SCSS：

  • Drupal.org上没有任何与 SCSS 相关的文档，但我们有 Drupal CSS 编码标准（这些可以应用于 SCSS 代码）。
  • 您可以在此处找到一些与 SCSSLint 相关的文档。
  • 另外，检查一下 Compass 的最佳实践也是不错的。

可重用性

我们正在深入研究这个问题。我们正在构建可复用的组件，这些组件可以在不同的网站（用途几乎相同）中使用。这些组件将提供基本的功能和样式，并可根据不同网站的需求进行覆盖。这里最重要的是确定哪些功能可以转换为组件。代码的可复用程度很大程度上取决于它与其他代码库的耦合程度。一个很好的例子是构建一个可以在大多数网站上使用的横幅滑块。

模块化的

这基本上意味着保持你的代码独立于其他代码，这样你的代码中一个错误的修改就不会破坏其他部分。这类似于面向对象编程中的耦合概念。这就好比将网站拆分成更易于管理的基本独立部分。

使用持续集成工具

我们使用 Travis CI。它是一款分布式持续集成服务，用于在 GitHub 上构建和测试项目。该服务对开源项目免费。你可能会想，为什么你之前没有用过它！😛 别担心，现在开始永远不会太晚，而且使用你的 GitHub 仓库设置起来也相当简单。

• 第一步是注册 Travis-CI，您也可以使用您的 github 帐户来完成此操作。
• 设置 .travis.yml 文件，该文件处理环境的构建以及 phpunit 文件的执行。

您可以在这里查看最简单的基本配置：

当您完成 phpunit 测试并且测试通过后，它将在您的提交中显示如下内容：

您可以在这里查看简单的 Travis 设置：

这.travis.yml应该位于项目的根目录下。Travis
仅在您在 Travis CI 中启用存储库后推送的提交上运行构建。

代码审查：
我们拥有非常完善的代码审查流程。不过这篇博文已经太长了，所以我会在下一篇博文中详细介绍。敬请期待。

原文请点击此处。感谢阅读 :)