PHP 编程/注释和风格

基本知识

PHP 编程
注释和风格

比较

当你编写更复杂的脚本时，你会发现你必须清楚地向自己和其他人解释你在做什么以及为什么这样做。注释和“良好”命名可以帮助你编写清晰易懂的脚本，因为

当编写一个持续时间超过一周的脚本时，在你完成时，你将不记得你在开始时做了什么，并且你很可能需要知道。
任何常用的脚本都会迟早需要重写。当你写下你所做的事情时，重写会容易得多（在许多情况下，重写成为可能）。
如果你想向别人展示你的脚本，它们应该美观整洁。

注释

注释是 PHP 解析器会跳过的代码部分。当解析器发现注释时，它只是在不执行任何操作的情况下一直执行到注释结束。PHP 提供单行注释和多行注释。

单行注释

单行注释是指从你开始的地方开始的注释，并在行尾结束。在 PHP 中，你可以使用 // 和 # 来创建单行注释（# 并不常用）。它们主要用于告诉读者你在接下来的几行中将做什么。例如

 //Print the variable $message
 echo $message;

重要的是要理解单行注释并不一定“遮蔽”整行，它从你开始的地方开始。因此，它也可以用来告诉读者某个变量的作用

 $message = ""; //This sets the variable $message to an empty string

$message = ""; 将被执行，但该行的其余部分不会被执行。

单行注释问题

单行注释以以下方式结束：

换行符（一个真正的换行符，而不是 \n 换行符）或
PHP 结束标签 ?>

如果单行注释以 PHP 结束标签关闭，则该注释将不会被注释。因此，以下代码将输出“2”

// echo "1"; ?> echo "2";

多行注释

这种注释可以跨越任意多行，可用于说明函数或类的作用，或者只是包含单行注释无法容纳的注释。要标记多行注释的开始，使用 /*，要标记结束，使用 */。例如

  /* This is a
  multiline comment
  And it will close
  When I tell it to.
  */

你也可以使用这种注释风格来跳过代码行的一部分。例如

  $message = ""/*this would not be executed*/;

尽管建议不要使用这种编码风格，因为它在某些编辑器中可能会造成混淆。

多行注释问题

未完成的多行注释会导致错误，除非它是在已存在的块注释块中开始（而不是关闭）（即，它不是贪婪的，而是只在完整的打开和关闭集中起作用）。
- 以下代码会导致错误
```
 /* test */ */
```
- 以下代码不会导致错误
```
 /* test /* */
```
因此，这些多行注释不能嵌套（第一个块直到“结束第一个注释”将被注释掉，但随后的 */ 将没有相应的 /* 开头）。因此，以下代码会导致错误

/*
Starting first comments
/*
Starting Nested comments
Ending nested comments
*/
Ending first comments
*/

可以通过组合注释风格来快速切换多个块（尽管这可能无法在文本编辑器中正确显示）。

原始文本，没有注释（因此输出“block one block two”

<?php
//*
print "block ";
print "one ";
// */
print "block ";
print "two";
?>

在第一行删除一个 / 后，第一个块被注释掉，只输出“block two”。

<?php
/*
print "block ";
print "one ";
// */
print "block ";
print "two";
?>

由于单行 // 覆盖了多行 /* .. */，因此可以同时切换两个代码块，进出注释模式。

原始文本（只输出“block one”）

<?php
//*
print "block";
print "one";
/*/
print "block";
print "two";
// */
?>

在第一行删除一个 / 后，第一个块被注释掉，第二个块被取消注释，只输出“block two”。

<?php
/*
print "block";
print "one";
/*/
print "block";
print "two";
// */
?>

phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html PHPDocumentor 使用多行注释（尽管开头紧跟着一个额外的星号“/**”）以及注释块中的其他标准化标签来自动创建文档。有关更多说明，请访问该网站。例如

<?php
/**
 * This is my new fancy code...
 * @author Dr. Who
 * @version 1.0
 */
?>

单行或多行注释问题

在正则表达式中使用以典型 "/" 作为分隔符的多行注释时，可能会出现冲突，因为表达式末尾的星号（以及关闭的 "/" 分隔符）可能会被解析为注释的关闭符，从而导致随后的 "*/" 缺少相应的打开符。

<?php
/*
$subject = "Hi Joe";
$matching = preg_match($subject, '/^Hi.*/');
*/

?>

为了避免这个问题，你可以

使用其他正则表达式分隔符——在大多数情况下可能不太常见（因此也需要转义）的分隔符（例如，除了电子邮件匹配之外的“@”可能比“/”不太常见）。
使用带有不可能条件的“if”语句，它可以

避免正则表达式冲突

<?php

if (0) {
  $subject = "Hi Joe";
  $matching = preg_match($subject, '/^Hi.*/');
}

?>

并避免嵌套问题

<?php

if (0) {

  if (0) {
    print "Hi ";
  }

  print "Bob";
}

?>

然而，"if" 方法的一个缺点是，文本编辑器可能无法识别它，因此不会进行代码着色（尽管这对于调试来说可能是一个优点，因为如果希望在运行代码测试时更清楚地看到注释掉的代码块，则可以这样做）。

风格

PHP 编码风格在 PHP 标准推荐中定义。

命名

正确命名变量、函数和类对于理解程序非常重要。按照惯例，应该使用驼峰命名法并且不使用任何缩写。

如果你定义以下变量

$var1 = "PHP";
$var2 = 15;

它们对任何人来说都没有什么意义。但如果你像这样定义

$programmingLanguage = "PHP";
$menuItems = 15;

则会更加清晰。但不要做得太过火。例如，$programmingLanguage 不是一个好的名称。它太长，而且会花费你很多时间来输入，并可能影响清晰度。一个更好的名称可能是 $progLanguage，因为它更短，但仍然易于理解。一个好的命名应该避免写注释来标记每个变量的作用。

例如，这些注释会占用脚本空间，应该删除

// The programming language used to write this script
$progLanguage = "PHP";

// The maximum number of items allowed in your personal menu
$maxMenuItems = 15;

魔术数字

在程序中使用数字时，它们必须具有明确的含义。例如，最好在早期定义 $menu_items，而不是反复使用 15 而不说明它的含义。对此的主要例外是数字 1；程序员通常需要从其他数字中加减 1 来避免“差一”错误，因此可以使用 1 而不定义它。

在早期定义数字的使用方式还可以更轻松地调整以后的值。同样，如果我们有 15 个菜单项，并且我们引用了它们十次，那么当我们添加第 16 个菜单项时，调整程序会容易得多；只需更正变量定义，你就可以在 10 个地方更新代码。

间距

PHP 会忽略多余的空格和空行。这意味着，即使你可以这样编写代码

if ($var == 1) {echo "Good";} else {echo "Bad";}

但最好按照 PSR-2 规范 ^[1]这样编写：

if ($var == 1) {
  echo "Good";
} else {
  echo "Bad";
}

一些程序员更喜欢这种编写方式

if ($var == 1)
{
  echo "Good";
}
else
{
  echo "Bad";
}

您还应该在脚本的不同部分之间使用空行。而不是

$var = 1;
echo "Welcome!&lt;br /&gt;";
echo "How are you today?&lt;br /&gt;";
echo "The answer: ";

if ($var == 1) {
  echo "Good";
} else {
  echo "Bad";
}

您可以这样写

$var = 1;

echo "Welcome!&lt;br /&gt;";
echo "How are you today?&lt;br /&gt;";

echo "The answer: ";

if ($var == 1) {
  echo "Good";
} else {
  echo "Bad";
}

这样，读者就会明白你的脚本首先声明了一个变量，然后欢迎用户，最后检查了变量。

指令

可以通过在 declare() 命令 ^[2]中编写一些指令来定义某些 PHP 编译行为。例如

 declare(encoding = "UTF-8");

参考资料

基本知识

PHP 编程
注释和风格

比较

[1] ttps://www.php-fig.org/psr/psr-2/

[2] ttps://php.ac.cn/manual/en/control-structures.declare.php

[1]

[2]