【PHP】03. 註解的寫法 Comment out

作者: 進度條編輯群更新日期: 2020/10/05

此文章也有影片介紹，可以搭配影片一起學習！

以下正式開始文章

這一堂我們來說明註解的用法～

初學的程式語言的時候，常會被一堆程式碼搞混，或是在臨摹線上課程時會有需要筆記的地方，這時候註解就派上用場了！

而進入職場後，程式碼可能是一群工程師共同撰寫，每個人都有自己撰寫程式碼的「風格」，你寫的程式碼除了要讓自己看的懂外，也必須讓協同工作的其他工程師們能夠理解，適當的註解可以節省溝通時間與維護程式碼的時間。

補充：
不過現在其實不提倡為了溝通而寫註解，因為註解常常不會跟著程式碼修改。非常容易發生註解並沒有隨著程式碼做修改反而增加溝通成本。或是修改的人不清楚註解的人所表達的意思。所以即使註解已經不符合現狀了卻還是不敢修改註解或是刪除它。久了反而製造大家的困擾。

因此現在比較提倡在變數與函數命名時就直接表達意思，這樣就不用多寫一遍。而且寫久了就會發現，如果一段程式碼需要註解才能讓人懂的話。那那段程式碼90%以上的可能性是寫得不好的。因為你沒辦法表達意圖。剩下的10%通常是演算法或是效能上的考量。

還有一個例外就是你需要利用註解來執行IDE(整合開發環境)的功能，例如你寫了註解就可以快速的利用開發環境獲取定義，有利於開發。或是可以自動化輸出說明書文件(跨團隊交流)。所以真實情況，還是等各位加入團隊後，再去做取捨。

簡單來說，PHP提供了三種註解方式：

一、單行註解 //

<?php

// 我是註解
// 我是第二行註解
echo "我不是註解<br/>";

// 註解可以隨便擺
?>

在該行的最前面加上//，則該行的程式碼則不會被執行，註解下一行會正常執行。如果你想註解的行數超過一行，可以使用下一種方式「多行註解」，而不須每行的前面都加上//。

二、多行註解 /* */
如果一次想註解多行，可在欲註解區塊的首末加上 /* 與*/，這時可以一次將多行程式碼註解掉，正因為註解的內容不會被執行，工程師常會利用多行註解對程式碼除錯或備份，也可以放在程式碼開頭作為版本說明用。

<?php

/*
echo "中間";
echo "都被";
echo "註解";
echo "掉了";
echo "啊啊啊！！！";
*/

?>

三、同樣是單行註解 #

<?php

# 我是註解

echo "我不是註解<br/>";

?>

和第一種方式一樣，在該行的最前面加上#，則該行的程式碼則不會被執行，而註解下一行會正常執行。

//與/**/是從C語言傳承下來的方式，而#是Linux上Shell Scripts的註解方式，以時代背景來說，PHP創造的年代明這兩種語言表達方式是相當主流的，也明顯的影響到其他的程式語言。

善用註解是一項好習慣也是一門藝術，不但可以增加程式碼的可讀性，當程式碼交給其他接手者維護時，也可以順便維護耳根清靜(誤)….。

最後順便提醒一下，註解掉程式碼用的是"Comment out"，並不是台式英文"mark掉"。所以跟國外開發者溝通的時候，不要一直叫人家Mark程式碼喔！