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

[1]

[2]