04 Ruby 的註釋
本章節主要帶大家瞭解註釋是什麼，為什麼要寫註釋以及在 Ruby 中如何使用註釋。
1. 什麼是註釋？
在計算機語言中，註釋是計算機語言的一個重要組成部分，用於在原始碼中解釋程式碼的功用，可以增強程式的可讀性，可維護性，或者用於在原始碼中處理不需執行的程式碼段，來除錯程式的功能執行。
註釋在隨原始碼進入前處理器或編譯器處理後會被移除，不會在目的碼中保留其相關資訊。——官方定義
簡而言之，註釋文字是為了能更好地解釋程式碼的功能，註釋程式碼是為了讓這部分程式碼不要執行。
那麼在 Ruby 中，我們如何使用註釋功能呢？
2. Ruby 中如何使用註釋
這裡我們要編輯 Ruby 指令碼來執行這些例子。
2.1 單行註釋
單行註釋＃字元開始，它們從＃直到該行結束。
# 這是一個單行註釋。
# puts "Hello, World!"
puts "Hello, Ruby!"
# ---- 輸出結果 ----
Hello, Ruby!
2.2 多行註釋
您可以使用 =begin和 =end 語法註釋多行。
=begin
puts "I'm Peter."
puts "I'm Andrew."
=end
puts "I'm Alice"
# ---- 輸出結果 ----
I'm Alice
Tips：多行註釋可擴充套件至任意數量的行，但
=begin和=end只能出現在第一行和最後一行。
3. 註釋的規範
-
儘量讓程式碼能夠自解釋，從而減少註釋的使用；
-
用空格將註釋符號和內容隔開；
-
避免多餘的註釋；
-
及時更新註釋，沒有註釋比過期的註釋更好；
-
英文的註釋往往更好，超過一個英文單詞的註釋首字母應該大寫並使用標點符號。
例項：
# 不好的例子
counter += 1 #increments counter by one
解釋：上面的例子中，我們應該將註釋符號和內容之間加一個空格。因為“increments counter by one”是一句話，所以我們應該首字母大寫且末尾要加標點符號.。
# 正確的例子
counter += 1 # Increments counter by one. Good code is like a good joke - it needs no explanation.
好的程式碼就像個玩笑-不需要解釋。
– Russ Olsen
3.1 註解
在工作中我們會經常用到註解功能，它是我們約定的一種註釋方式，用來分類並提示在工作中，我們接下來要做的一些事情。
常用的註解有下面幾種：
| 關鍵字 | 什麼時候使用 |
|---|---|
| TODO | 備註缺失的特性或者在以後新增的功能 |
| FIXME | 備註有問題需要修復的程式碼 |
| OPTIMIZE | 來備註慢的或者低效的可能引起效能問題的程式碼 |
| HACK | 備註那些使用問題程式碼的地方可能需要重構 |
| REVIEW | 來備註那些需要反覆檢視確認工作正常的程式碼。例如： REVIEW: 你確定客戶端是怎樣正確的完成 X 的嗎？ |
經驗：
-
註解應該寫在緊接相關程式碼的上方；
-
註解關鍵字後跟一個冒號和空格，然後是描述問題的記錄；
-
如果需要多行來描述問題，隨後的行需要在
#後面縮排兩個空格； -
註解不應該放在行尾而沒有任何備註。
例項：
# 錯誤的例項
def bar
sleep 100 # OPTIMIZE
end
例項：
# 正確的例項
def bar
# FIXME: This has crashed occasionally since v3.2.1. It may
# be related to the BarBazUtil upgrade.
baz(:quux)
end
4. 小結
本章中，您掌握了在 Ruby 中使用#來進行單行註釋、使用=begin和=end來進行多行註釋，瞭解了註釋的基本規範與註解。
讓我們趁熱打鐵繼續學習下一章節。