54

我正在尝试在我们的持续集成服务器上设置PHP CodeSniffer,以提高我们代码库的质量。阅读文档后,我对规范化和执行我们的编码标准的想法感到非常兴奋。但是,我想知道我们产品的实际改进。我很清楚,嗅探器只检测到对定义的编码标准的违反,但干净、一致的代码库提供了哪些类型的好处?用 100k+ 行代码重构一个项目以符合 PEAR 标准是否值得付出额外的工作?

对于那些不熟悉 PHP CodeSniffer 或 code-smell 的人,这里有一个示例输出:

文件:/path/to/code/myfile.php
发现 5 个错误影响 2 行
-
2 | 错误 | 缺少文件文档注释
20 | 错误 | PHP 关键字必须小写;预期为“假”,但发现“假”
47 | 错误 | 行没有正确缩进;预期 4 个空格,但找到 1
51 | 错误 | 缺少功能文档注释
88 | 错误 | 行没有正确缩进;预计有 9 个空格,但找到了 6 个

严格来说,用户/客户不会注意到被重构为符合标准的产品有任何区别,但我想知道是否还有其他隐藏的好处

现在我们的代码绝不马虎,我们尝试遵循我们自己的个人标准,这些标准大部分来自Pear 的编码标准,但训练有素的眼睛可以发现差异。

所以我的问题是它们能在多大程度上提高产品的质量。它带来了什么样的潜在利益?

我是否只是因为想要让我们的产品更接近一套标准而产生强迫症?值得吗?如果是这样,您使用什么样的策略来实现代码嗅探器并纠正检测到的后续违规行为?

4

8 回答 8

104

首先,我是 PHP_CodeSniffer 的维护者,所以我显然对这方面有偏见。但在我作为 PHP 开发人员的 10 年中,我也研究过一些大型代码库,所以我希望我能提出一些具体的理由来说明为什么编码标准是一件好事。我可以写一个关于这个主题的博客系列,但我只会给你一个关于 PHP_CodeSniffer 是如何产生的小故事,这样你就可以理解该工具为我解决的问题。

我参与过一些大型 CMS 项目。第一个背后有一堆代码和一个相对较小的开发团队。我们没有标准。但我们没有真正的问题。这个团队很小,在一起呆了很长一段时间。我们已经习惯了。

然后我们建立了一个新的CMS。我们刚开始时只有几个开发人员。当时我是一个只有两个开发人员的团队的一员。同样,编码标准并没有给我们带来任何问题。我和其他开发人员来自相同的背景,并且已经制定了一些我们遵循的准则。那时我们不需要 PHPCS。

但该团队一次只培养了一名开发人员,最终达到了 12 名全职开发人员,其中不少人来来去去。有些来自旧的 CMS,有些来自公司外部。所有人都有不同的背景和不同的发展方法。很明显谁写了什么代码,因为风格如此不同。每当您处理复杂的事情时,您首先必须适应他们的风格,因为这不是您习惯于查看代码的方式。这就像第一次读莎士比亚。您需要先习惯它,然后才能以自然的节奏阅读。

对于开发人员来说,不得不停下来找出另一种编码风格的额外时间纯粹是浪费时间。当您陷入间距、缩进和括号位置的困境时,这是一个想法溜走的机会。归根结底,这些事情都无关紧要。但是让我告诉你,如果它们导致开发人员中断他们的流程,它们就很重要。所以我们需要一种方法来让他们不碍事,让开发人员做他们最擅长的事情。

同时,我们对 JavaScript 进行了更多的研究。一种新的语言,风格通常被抛到窗外。代码是从示例站点复制/粘贴并混合在一起的。在学习用新语言开发复杂代码时,找到一种让我们的 JS 看起来与 PHP 相似的方法是有意义的。我们可以稍后将其最小化,但我们需要能够在语言之间快速切换,再次保持我们的流畅度。

所以 PHP_CodeSniffer 就是为此而生的。它可以帮助开发人员使用相同的编码风格,使格式和其他诱饵问题完全消失。它允许您在一定程度上像对待 PHP 一样对待您的 JS。我用它来检测产品特定的气味,比如未翻译的字符串或开发人员没有使用我们正确的类包含代码。我还将它用于特定语言的气味,例如确保不会留下杀死 IE 的 JS 逗号。你可以用它来做任何你想做的事。它带有大量可以使用XML 规则集文件轻松合并在一起的嗅探器。你也可以自己写。您可以集成第三方工具,使其成为静态代码分析的一站式商店。您可以根据自己的喜好认真对待标准和代码气味。

PHP_CodeSniffer 与任何开发工具一样,应该适合您。你不为它工作。如果它产生了太多您不关心的错误,请自定义标准以删除您不想要的错误,或者将错误变成警告。但是,如果我的故事听起来像是您正在经历或将来可能会经历的事情,那么值得仔细查看 PHP_CodeSniffer 以了解它是否可以帮助您。

我希望这可以帮助您和其他人理解为什么编码标准对某些项目和开发人员非常重要。这与细节无关。这是关于从导致开发人员失去焦点的事情列表中删除编码风格。

于 2011-05-12T22:41:44.790 回答
32

拥有编码风格约定是一个好主意,因为它可以帮助开发人员在处理不是他们编写的代码时不会被以不同风格编写的代码分心。它会让你的代码库表面上更干净。如果您可以将其自动化,那就太好了,但通常不需要费尽心思去遵守(除非当前的风格很糟糕)。如果你已经有了一个足够好的标准,那就坚持下去。

不过,代码气味有所不同:它是(一组)症状,可能表明代码存在更深层次的问题。示例是圈复杂度、长方法名称、大型类、无法描述的名称、重复代码等。这通常会带来更多问题,因为它可能会彻底损害代码的可维护性。你绝对应该解决这些问题。

PHP CodeSniffer 似乎主要用于检查样式约定,而不是代码气味。如果您可以使用它来帮助执行样式约定,那就太好了。但请注意,它不会使您的代码库变得更好。您将需要进行手动审核以完成此操作。

如果您想使用它来检查您是否符合当前标准,这似乎是可能的,请参阅问题“我不同意您的编码标准!我可以让 PHP_CodeSniffer 强制执行我自己的标准吗?”的答案。在他们的常见问题解答中。

于 2009-06-11T18:06:01.817 回答
11

把我算在传播 CodeSniffer 的人中。在多年来高度怀疑之后,我现在在我正在从事的每个项目中都使用它。为什么?

正如 Grace Hopper 和/或 Andrew Tanenbaum 所说,

标准的美妙之处在于您有很多选择。

同样,创建自己的编码标准几乎总是一个 Bad Idea™;创建一个足以涵盖所有代码的全面性是困难的,更重要的是,维护您的代码的下一个人不会喜欢,他们会尝试“改进”您的标准,以使其适合他的长期-持有编码风格。采用适当的外部标准,无论是 Zend、PEAR、Kohana 还是 JoeBobBriggsAndHisFifthCousin,都可以让您专注于内容而不是格式。更好的是,像 PHP CodeSniffer 这样的工具要么支持标准的“新鲜出炉”,要么之前的工具几乎可以肯定地将支持作为附加组件实现。

除非您采用两个简单的互补规则,否则将编码标准与未编写到该标准的现有代码混合使用会很合适。

--ignore通过命令行选项或等效的配置文件设置,排除在您采用编码标准之前的 文件。但是,当您修改源文件的任何部分时,请更新整个文件以符合您选择的标准。

我刚刚写了一篇关于这类事情的新博客文章。

于 2010-07-28T14:56:07.480 回答
6

有很多情况需要人工判断,而 CodeSniffer 没有。

一致的括号,缩进改进了代码。函数调用中逗号后缺少空格?可能可以原谅,但根据 CodeSniffer ,这是错误的。

恕我直言,CS报告的错误太多了。即使是看起来有简洁代码的项目也很容易遇到数以千计的 CS 问题。解决所有这些问题很快就会变得很累,而且几乎不可能解决,尤其是当它混合了真正的问题和强迫性的胡说八道时——两者同样经常被标记为ERRORS

您最好忽略 CS 并花时间对代码进行实际改进(在设计、算法方面),而不是完全肤浅的空白和注释更改(1 行isAlpha函数真的需要 8 行注释吗?是的,如果你问 CS)。

CS 很容易成为打磨工具。

于 2009-06-12T22:13:40.013 回答
3

这绝对是一件好事。我们从 SVN 挂钩运行我们的代码,因此所有代码都必须通过内部标准(来自 PEAR 的修改)才能提交(这是我做过的最好的决定之一)。

当然,这最适合新项目,因为没有大量遗留代码可以转换为新标准。解决此问题的一种方法是修改您的 SVN 预提交挂钩以仅运行代码嗅探器的新添加并忽略修改。您可以通过添加以下行来做到这一点:

$SVNLOOK changed "$REPOS" -t "$TXN" | grep "^A.*\.php " > /dev/null || exit 0

如果没有要解析的新 PHP 代码,这将退出钩子脚本。因此,所有新文件都需要遵守标准,您可以在自己的时间将遗留代码升级到标准。

于 2009-08-26T22:40:44.740 回答
3

请注意,如果您使用的是 Eclipse 或 Zend IDE,您可以从自动化工具中受益,这些工具可以降低遵守标准的成本。您还可以使用持续集成工具,例如 Hudson 或 PHPUndercontrol。

  • PDT 是一个很酷的 PHP 编辑器
  • PDT-Tools 是一些带有自动格式化工具的 PDT 插件
  • DTLK(动态工具包库)可用于启动一些外部脚本来检查您的文件。

您还可以查看我认为更容易配置的PHP Checkstyle (免责声明:我已经研究过了)

网站的“文档”页面上列出了一些其他工具。

于 2010-06-01T12:06:52.877 回答
1

CodeSniffer 是一个很好实现的东西,但你必须知道如何使用它。除非您因为将工作提交给某个外部项目而必须遵守给定的编码标准,否则您可以自由地完全定义自己的编码标准。

PHP CodeSniffer 应该让你很容易做到这一点,因为已经有很多单一的代码嗅探可以包含在你自己的编码标准定义中,而无需从头开始编写它们。在探索现有 Codesniffer 的可能性时,如果您觉得有必要,您最终可能会为现有嗅探或自己的嗅探编写扩展。

如果您想从 CodeSniffer 开始,第一步是获取一组与您当前编码标准完全相似的嗅探,并检查产生的错误和警告。不要应用预定义的标准之一,因为如果修复,这很可能会导致太多错误而收益太少。例如,如果您不使用 PHPDoc 生成文档,那么完成所有关于缺少 PHPDoc 标记和注释的代码嗅探器错误是没有用的。

于 2010-06-07T11:32:11.253 回答
0

您是否通过 PEAR/PECL 提供用于公共分发的 PEAR 包?如果是这样,那么您可能想要坚持 PEAR 约定。

否则,我看不出它值得大重构。最重要的是就您的团队的编码标准达成一致……不必是 PEAR 的标准……只要确保执行了一些标准约定。

例如,我是

function foo () {

格式与 PEAR 标准..

function foo ()
{

最重要的是,如果要进行大量工作,请不要太担心是否符合他们的标准,尤其是如果您没有将软件包放在 PECL 上。

于 2009-06-11T18:14:45.447 回答