PHP 编程/注释和风格

基础知识

PHP 编程
注释和风格

比较

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

当编写一个持续时间超过一周的脚本时，到您完成时，您将不记得您开始时做了什么，而且您很可能需要知道。
任何常用的脚本都需要 sooner or later 重写。当您记录下自己所做的事情时，重写会更容易（并且在许多情况下成为可能）。
如果您想向某人展示您的脚本，它们应该干净整洁。

注释

注释是 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
*/

可以通过组合不同的风格来快速切换多个块（但这在文本编辑器中可能无法正确显示）

原始文本，没有注释掉任何内容（因此打印“块一块二”

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

在第一行删除一个 / 后，第一个块被注释掉，只打印“块二”

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

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

原始文本（只打印“块一”）

<?php
//*
print "block";
print "one";
/*/
print "block";
print "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 个菜单项，并且我们在 10 个地方引用它们，那么当我们添加第 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() 命令中编写一些指令来定义某些 PHP 编译行为。^[2] 例如

 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]