編寫Ruby代碼注釋時需要注意的一些問題
更新時間：2015年08月03日 11:43:30 投稿：goldensun
這篇文章主要介紹了編寫Ruby代碼注釋時需要注意的一些問題,特別是在團隊協(xié)作時好的注釋能大大增加代碼的可讀性,需要的朋友可以參考下
寫出自解釋文檔代碼，然后讓這部分歇息吧。這不是說著玩。
使用英文編寫注釋。
使用一個空格將注釋與符號隔開。
注釋超過一個單詞了，應(yīng)句首大寫并使用標點符號。句號后使用 一個空格
避免多余的注釋。
# bad counter += 1 # increments counter by one
隨時更新注釋，沒有注釋比過期的注釋更好。
不要為糟糕的代碼寫注釋。重構(gòu)它們，使它們能夠“自解釋”。(Do or do not - there is no try.)
注解應(yīng)該寫在緊接相關(guān)代碼的上方。
注解關(guān)鍵字后跟一個冒號和空格，然后是描述問題的記錄。
如果需要多行來描述問題，隨后的行需要在 # 后面縮進兩個空格。
def bar # FIXME: This has crashed occasionally since v3.2.1. It may # be related to the BarBazUtil upgrade. baz(:quux) end
如果問題相當明顯，那么任何文檔就多余了，注解也可以（違規(guī)的）在行尾而沒有任何備注。這種用法不應(yīng)當在一般情況下使用，也不應(yīng)該是一個 rule。
def bar sleep 100 # OPTIMIZE end
使用 TODO 來備注缺失的特性或者在以后添加的功能。
使用 FIXME 來備注有問題需要修復(fù)的代碼。
使用 OPTIMIZE 來備注慢的或者低效的可能引起性能問題的代碼。
使用 HACK 來備注那些使用問題代碼的地方可能需要重構(gòu)。
使用 REVIEW 來備注那些需要反復(fù)查看確認工作正常的代碼。例如： REVIEW: 你確定客戶端是怎樣正確的完成 X 的嗎？
使用其他自定義的關(guān)鍵字如果認為它是合適的，但是確保在你的項目的 README 或者類似的地方注明。
您可能感興趣的文章:
相關(guān)文章
這篇文章主要介紹了詳細解析Ruby中的變量,是Ruby學(xué)習中最基礎(chǔ)的知識之一,需要的朋友可以參考下2015-05-05
這篇文章主要介紹了Ruby多線程庫(Thread)使用方法詳解,需要的朋友可以參考下2022-04-04
Ruby on Rails網(wǎng)站項目構(gòu)建簡單指南
Rails項目通過Ruby世界中的gem和rake工具來構(gòu)建起來真的相當方便,這里就給大家整理了一份Ruby on Rails網(wǎng)站項目構(gòu)建簡單指南,需要的朋友可以參考下2016-06-06
本文給大家分享的是個人使用ruby編寫的抓取網(wǎng)頁圖片的代碼，十分的簡單實用，有需要的小伙伴可以參考下。2016-04-04
詳解Ruby on Rails中的mailer相關(guān)使用
這篇文章主要介紹了詳解Ruby on Rails中的mailer相關(guān)使用,主要針對其相關(guān)的編程風格給出建議,需要的朋友可以參考下2015-08-08
對于rails的一些使用技巧的代碼2009-01-01
這篇文章主要介紹了Ruby 迭代器的的相關(guān)資料，文中示例代碼非常詳細，供大家參考和學(xué)習，感興趣的朋友可以了解下2020-06-06
這篇文章主要介紹了Ruby中的循環(huán)語句的用法教程,邏輯循環(huán)語句是每門編程語言的基礎(chǔ),需要的朋友可以參考下2015-05-05
這篇文章主要介紹了在Docker中部署Ruby on Rails的教程,Docker是當下最火的虛擬機,而本文所介紹的Ruby on Rails的部署則充分利用了Ruby中的rake這一炫酷的實現(xiàn)自動化的方法,需要的朋友可以參考下2015-06-06
本文主要給大家講訴的是如何搭建redis集群的方法以及在此過程中需要注意的問題，非常不錯，推薦給大家，有需要的小伙伴可以來參考下2017-09-09