Ruby 的注釋

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

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

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

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

2. Ruby 中如何使用注釋

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

2.1 單行注釋

單行注釋＃字符開(kāi)始，它們從＃直到該行結(jié)束。

# 這是一個(gè)單行注釋。
 
# puts "Hello, World!"
puts "Hello, Ruby!"

# ---- 輸出結(jié)果 ----
Hello, Ruby!

2.2 多行注釋

您可以使用 =begin和 =end 語(yǔ)法注釋多行。

=begin
puts "I'm Peter."
puts "I'm Andrew."
=end
puts "I'm Alice"

# ---- 輸出結(jié)果 ----
I'm Alice

Tips：多行注釋可擴(kuò)展至任意數(shù)量的行，但=begin 和 =end 只能出現(xiàn)在第一行和最后一行。

3. 注釋的規(guī)范

1. 盡量讓代碼能夠自解釋?zhuān)瑥亩?strong>減少注釋的使用；

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

3. 避免多余的注釋?zhuān)?/p>

4. 及時(shí)更新注釋?zhuān)瑳](méi)有注釋比過(guò)期的注釋更好；

5. 英文的注釋往往更好，超過(guò)一個(gè)英文單詞的注釋首字母應(yīng)該大寫(xiě)并使用標(biāo)點(diǎn)符號(hào)。

實(shí)例：

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

解釋：上面的例子中，我們應(yīng)該將注釋符號(hào)和內(nèi)容之間加一個(gè)空格。因?yàn)椤癷ncrements counter by one”是一句話(huà)，所以我們應(yīng)該首字母大寫(xiě)且末尾要加標(biāo)點(diǎn)符號(hào).。

# 正確的例子
counter += 1 # Increments counter by one. 

Good code is like a good joke - it needs no explanation.

好的代碼就像個(gè)玩笑-不需要解釋。

– Russ Olsen

3.1 注解

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

常用的注解有下面幾種：

經(jīng)驗(yàn)：

1. 注解應(yīng)該寫(xiě)在緊接相關(guān)代碼的上方；

2. 注解關(guān)鍵字后跟一個(gè)冒號(hào)和空格，然后是描述問(wèn)題的記錄；

3. 如果需要多行來(lái)描述問(wèn)題，隨后的行需要在 # 后面縮進(jìn)兩個(gè)空格；

4. 注解不應(yīng)該放在行尾而沒(méi)有任何備注。

實(shí)例：

# 錯(cuò)誤的實(shí)例
def bar
  sleep 100 # OPTIMIZE
end

實(shí)例：

# 正確的實(shí)例
def bar
  # FIXME: This has crashed occasionally since v3.2.1. It may
  #  be related to the BarBazUtil upgrade.
  baz(:quux)
end

4. 小結(jié)

本章中，您掌握了在 Ruby 中使用#來(lái)進(jìn)行單行注釋、使用=begin和=end來(lái)進(jìn)行多行注釋?zhuān)私饬俗⑨尩幕疽?guī)范與注解。

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