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.net.tw/manual/en/control-structures.declare.php

[1]

[2]