Ruby 的注釋

本章節(jié)主要帶大家了解注釋是什么，為什么要寫注釋以及在 Ruby 中如何使用注釋。

1. 什么是注釋？

在計算機語言中，注釋是計算機語言的一個重要組成部分，用于在源代碼中解釋代碼的功用，可以增強程序的可讀性，可維護性，或者用于在源代碼中處理不需運行的代碼段，來調(diào)試程序的功能執(zhí)行。
注釋在隨源代碼進入預處理器或編譯器處理后會被移除，不會在目標代碼中保留其相關信息。——官方定義

簡而言之，注釋文字是為了能更好地解釋代碼的功能，注釋代碼是為了讓這部分代碼不要運行。

那么在 Ruby 中，我們?nèi)绾问褂米⑨尮δ苣兀?/p>

2. Ruby 中如何使用注釋

這里我們要編輯 Ruby 腳本來執(zhí)行這些例子。

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：多行注釋可擴展至任意數(shù)量的行，但=begin 和 =end 只能出現(xiàn)在第一行和最后一行。

3. 注釋的規(guī)范

1. 盡量讓代碼能夠自解釋，從而減少注釋的使用；

2. 用空格將注釋符號和內(nèi)容隔開；

3. 避免多余的注釋；

4. 及時更新注釋，沒有注釋比過期的注釋更好；

5. 英文的注釋往往更好，超過一個英文單詞的注釋首字母應該大寫并使用標點符號。

實例：

# 不好的例子
counter += 1 #increments counter by one

解釋：上面的例子中，我們應該將注釋符號和內(nèi)容之間加一個空格。因為“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 注解

在工作中我們會經(jīng)常用到注解功能，它是我們約定的一種注釋方式，用來分類并提示在工作中，我們接下來要做的一些事情。

常用的注解有下面幾種：

經(jīng)驗：

1. 注解應該寫在緊接相關代碼的上方；

2. 注解關鍵字后跟一個冒號和空格，然后是描述問題的記錄；

3. 如果需要多行來描述問題，隨后的行需要在 # 后面縮進兩個空格；

4. 注解不應該放在行尾而沒有任何備注。

實例：

# 錯誤的實例
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來進行多行注釋，了解了注釋的基本規(guī)范與注解。

讓我們趁熱打鐵繼續(xù)學習下一章節(jié)。