編寫Ruby代碼注釋時(shí)需要注意的一些問(wèn)題
寫出自解釋文檔代碼，然后讓這部分歇息吧。這不是說(shuō)著玩。
使用英文編寫注釋。
使用一個(gè)空格將注釋與符號(hào)隔開(kāi)。
注釋超過(guò)一個(gè)單詞了，應(yīng)句首大寫并使用標(biāo)點(diǎn)符號(hào)。句號(hào)后使用 一個(gè)空格
避免多余的注釋。
# bad counter += 1 # increments counter by one
隨時(shí)更新注釋，沒(méi)有注釋比過(guò)期的注釋更好。
不要為糟糕的代碼寫注釋。重構(gòu)它們，使它們能夠“自解釋”。(Do or do not - there is no try.)
注解應(yīng)該寫在緊接相關(guān)代碼的上方。
注解關(guān)鍵字后跟一個(gè)冒號(hào)和空格，然后是描述問(wèn)題的記錄。
如果需要多行來(lái)描述問(wèn)題，隨后的行需要在 # 后面縮進(jìn)兩個(gè)空格。
def bar # FIXME: This has crashed occasionally since v3.2.1. It may # be related to the BarBazUtil upgrade. baz(:quux) end
如果問(wèn)題相當(dāng)明顯，那么任何文檔就多余了，注解也可以（違規(guī)的）在行尾而沒(méi)有任何備注。這種用法不應(yīng)當(dāng)在一般情況下使用，也不應(yīng)該是一個(gè) rule。
def bar sleep 100 # OPTIMIZE end
使用 TODO 來(lái)備注缺失的特性或者在以后添加的功能。
使用 FIXME 來(lái)備注有問(wèn)題需要修復(fù)的代碼。
使用 OPTIMIZE 來(lái)備注慢的或者低效的可能引起性能問(wèn)題的代碼。
使用 HACK 來(lái)備注那些使用問(wèn)題代碼的地方可能需要重構(gòu)。
使用 REVIEW 來(lái)備注那些需要反復(fù)查看確認(rèn)工作正常的代碼。例如： REVIEW: 你確定客戶端是怎樣正確的完成 X 的嗎？
使用其他自定義的關(guān)鍵字如果認(rèn)為它是合適的，但是確保在你的項(xiàng)目的 README 或者類似的地方注明。
相關(guān)文章
Ruby中使用SWIG編寫ruby擴(kuò)展模塊實(shí)例
這篇文章主要介紹了Ruby中使用SWIG編寫ruby擴(kuò)展模塊實(shí)例,SWIG是一種簡(jiǎn)化腳本語(yǔ)言與C/C++接口的開(kāi)發(fā)工具,需要的朋友可以參考下2014-09-09
數(shù)據(jù)是隨機(jī)的，所以每次的記錄都會(huì)不同。2008-11-11
這篇文章主要介紹了Ruby中相等性判斷的4種方法,本文講解了“==” 最常見(jiàn)的相等性判斷、“===” 用于 case 語(yǔ)句的相容判斷、“equal?” 相同對(duì)象判斷、“eql?” 對(duì)象 hash 值判斷等內(nèi)容,需要的朋友可以參考下2015-03-03
這篇文章主要介紹了Lua中的表的概念及其相關(guān)操作方法,是Lua入門學(xué)習(xí)中的基礎(chǔ)知識(shí),需要的朋友可以參考下2015-05-05
詳解Ruby語(yǔ)言中的注釋用法與中文編碼問(wèn)題
這篇文章主要介紹了Ruby語(yǔ)言中的注釋用法與中文編碼問(wèn)題,是Ruby入門學(xué)習(xí)中的基礎(chǔ)知識(shí),需要的朋友可以參考下2015-10-10
Ruby中實(shí)現(xiàn)統(tǒng)計(jì)文件行數(shù)、單詞數(shù)和字符數(shù)
這篇文章主要介紹了Ruby中實(shí)現(xiàn)統(tǒng)計(jì)文件行數(shù)、單詞數(shù)和字符數(shù),本文是自定義的一個(gè)函數(shù),需要的朋友可以參考下2015-01-01
這篇文章主要介紹了Ruby中的異常處理代碼編寫示例,作者對(duì)異常處理的方式給出了一些比較通用的建議,需要的朋友可以參考下2015-08-08
取得指定月日期數(shù)的Ruby代碼2009-05-05
Rails中使用MySQL分區(qū)表一個(gè)提升性能的方法
這篇文章主要介紹了Rails中使用MySQL分區(qū)表一個(gè)提升性能的方法,本文總結(jié)出了一個(gè)簡(jiǎn)單的方法實(shí)現(xiàn)避免掃描全部的分區(qū)表,從而提升性能,需要的朋友可以參考下2015-03-03
設(shè)計(jì)模式中的觀察者模式在Ruby編程中的運(yùn)用實(shí)例解析
這篇文章主要介紹了設(shè)計(jì)模式中的觀察者模式在Ruby編程中的運(yùn)用實(shí)例解析,觀察者模式中主張?jiān)O(shè)立觀察者對(duì)象來(lái)降低對(duì)象之間的耦合,需要的朋友可以參考下2016-04-04