特定于 PHP - 干净的代码、命名约定和文档答案

【问题标题】：PHP specific - clean code, naming conventions and documentation特定于 PHP - 干净的代码、命名约定和文档
【发布时间】：2009-11-18 17:13:55
【问题描述】：

对于干净的代码、命名约定和 PHP 文档，有哪些最佳实践？

我看到用户/人们说这是一种不好的做法，例如：

// Create an array to hold x values
$arr_x = array();

这是一个不必要的注释，因为语法本身就解释了功能。那应该更像是描述脚本/函数功能而不是程序的变量/流程的标题注释。示例

/**
 * Create an array
 */
function create_array() {
   return array();
}

$arr_x = create_array();

// This is just to show the comments and the code is not tested or used except for this example

这使我走上了正确的语法、编码和文档的道路（标题命名的原因）。

对于变量、函数和脚本命名约定，什么是可接受的，或者这是个人偏好？

$varX
function varX()
varX.php

或

$var_x
function var_x()
var_x.php

我正在尝试查找是否有我应该遵守的标准。谢谢

【问题讨论】：

标签： php syntax coding-style

【解决方案1】：

Zend Framework 有一个 PHP 编码标准文档 here，它应该涵盖诸如如何命名变量和函数之类的内容。

何时以及如何发表评论与平台无关。我认为一个好的一般规则是评论为什么做某事，而不是如何。代码应该写得足够清楚，以使如何显而易见。（当然也有例外，例如使用可能需要解释的特别复杂的算法。）

【讨论】：

谢谢，我得调查一下

【解决方案2】：

没有标准，只有开发者的意见。

我更喜欢用下划线分隔变量：

$my_var

但对于函数我更喜欢驼峰式：

function myFunction() {}

至于 cmets，是的，有时根本不需要诸如 // create array 之类的 cmets，但不要使用一个衬里来推迟，它们不会在执行脚本时减慢您的脚本速度。我喜欢用一句话来整齐地描述复杂脚本的每一步。

只要您的代码对您和您的其他开发人员（项目中的其他人、第三部分公司等）可读，那么您就可以了。

【讨论】：

默认情况下，PHP 语言对所有函数和变量使用_unserscores_names。 JavaScript 等其他语言默认使用 CamelCase。

【解决方案3】：

最重要的是保持一致。除了描述性变量、函数和方法名称等基础知识之外，真正重要的是一致性。

如果您不想考虑太多，请随意使用其中一种流行的编码风格指南，例如 PEAR 项目中的指南，或 JacobM 刚刚发布的 Zend Framework 标准。

【讨论】：

【解决方案4】：

我使用 codeigniter，这是他们的风格指南。
http://codeigniter.com/user_guide/general/styleguide.html

【讨论】：

【解决方案5】：

找到您喜欢的标准，或与您现有代码库最接近的标准，由php_codesniffer 支持 - 并安装该工具 - 至少您有一个工具可以检查您的代码是否存在差异。

【讨论】：

【解决方案6】：

一个重要的事情是一致性。无论你为你的开发团队选择什么——上面提到的任何标准——确保你的开发组织中的每个人都遵守它。否则，代码将很难阅读，代码审查也将变得困难。

【讨论】：

【解决方案7】：

Drupal 是用 PHP 编写的最大的开源代码库之一。

他们必须有一些好的代码约定。

http://drupal.org/coding-standards

【讨论】：

【解决方案8】：

php 中的编码标准一直在变化。如果您查看较旧的框架，它们都使用 Camel 案例，我认为这可能会导致代码错误。这对像 java 这样的语言有意义，但对 php 没有意义。

最近的编码标准和框架工作避免使用驼峰式大小写，并且偏好使用小写下划线分隔的变量名称。例如：fat_yak，而不是 fatYak。

php 的问题是它会接受一个未声明的新变量，而且由于大小写很重要，所以可能有两个变量同名，但大小写不同。因此，重要的是始终对变量使用小写，以避免简单的错误，否则可能无法检测到。同样的原则应该扩展到方法名，因为在编写扩展类和覆盖方法名时会遇到同样的问题。（可能会放错大写字母并最终得到第二个函数，而不是按照您的意图替换原始函数。）

我认为有一些非常精细的编码标准被这个驼峰式格式所破坏。

这个原则也应该扩展到文件名。鉴于 unix 服务器在大小写方面与 Windows 服务器不同，恕我直言，始终使用小写字母可以避免许多问题。但是，以大写首字母命名的类可能是一种严重的邪恶。

在类名中使用 CamelCase 很好。如果您在这里犯了错误，它将立即被捡起。事实上，为了您自己的理智，在课程开始时使用大写字母是强制性的。（我会将它们命名为 Fat_yak，而不是 FatYak，但我在那个方面是少数，所以请闭嘴.. 虽然它会使命名文件更容易.. 例如：Fat_yak.php 而不是 FatYak.php）

使用 4 个空格而不是一个制表符是一个非常有用的想法，尤其是在使用许多不同的编辑器时。（代码在所有编辑器上看起来都一样）

其他一切都是 50-50 的命题。每个标准似乎都在两个选项中选择一个。这是编码标准令人失望的方面，因为没有出现明确的领导者。

eg: 
"true" or "TRUE"

eg:
function blah(){

}

or

function blah()
{

}

【讨论】：

【解决方案9】：

我称之为反模式。当数据类型发生变化时你会怎么做？您是否会更改整个项目以及可能使用您的代码的许多其他项目？

我宁愿使用简单的：

$x
function x()
x.php

【讨论】：

对不起，这只是一个例子，但我对你真正想说的很感兴趣。你能再解释一下吗？

【解决方案10】：

JacobM 刚刚发布了一个很好的 PHP 标准文档。但是，如果我正在编辑或添加到现有代码，我会尝试遵循前作者制定的样式。

【讨论】：