1. 文件命名
文件的命名(File Names)
文件的命名應該以.R爲結尾,並且應該有意義(你要幹什麼)
GOOD: predict_ad_revenue.R
BAD: foo.R標誌符(Identifiers)
標誌符的命名分爲變量的命名和函數的命名。
在標誌三符中不要使用_和-。標誌符的命名應該遵循一貫的原則。原則如下:變量的命名(variable.name):全部用小寫字母,字(word)與字(word)之間應該用小黑點(.)隔開
GOOD: avg.clicks
BAD: avg_Clicks , avgClicks函數的命名(FunctionName):每一個字(word)的首個字符大寫,字與字之間沒有間隔.
GOOD: CalculateAvgClicks
BAD: calculate_avg_clicks , calculateAvgClicks
每一個函數的命名要以動詞開始(做什麼事)
例外情況:當創建一個類的對象,構造器(constructor) 和類名應該保持一致。(所有的面向對象應該都適用)- 常量的命名(kConstantName):和函數命名方式一樣,除了最前面要加一個小寫的k.
2. 語法(Syntax)
每一代碼行的長度
最大的長度不能超過80個字符首行縮進
當縮進你的代碼時,使用兩個空格的長度。禁忌:不要使用TAB鍵或空格和TAB混合方式
例外情況: Exception: When a line break occurs inside parentheses, align the wrapped line with the first character inside the parenthesis.(翻譯不出來,前後語意應該保持一致)
可能翻譯如下(猜測):當括號中的代碼太多,你準備寫成兩行或者多行的時候,那麼保證下一行的開始部分與該括號第一個字符列對齊。
如下:
上面實例出自說明文檔,大部分內容都是在一個括號內,但是不同行和括號的開頭部分是列對齊的。上面這段話也說明一個技巧:
R的幫助文檔很強大,如果在code style 上有疑惑,則查詢幫助文檔即可。空格
請在所有的二元操作符(+, -, *, <-, etc)兩邊都加上空格.
逗號前一定不能有空格,逗號後一定得有空格。
(上面那個例子,注意看等號。)
GOOD:
tabPrior <- table(df[df$daysFromOpt < 0, “campaignid”]) #說明[並不是一個二元操作符。
total <- sum(x[, 1])
total <- sum(x[1, ])
BAD:
左括號前面,要加一個空格,除了調用函數的時候。
例外情況:Exception: Spaces around =’s are optional when passing parameters in a function call.
這裏並不知道 =’s 指的是什麼?s指的是space
可能翻譯:
在函數調用的時候,函數中等號左右的space是可選的。(應該對於所有的語言都是適用的)
GOOD:
if (debug)
BAD:
if(debug)
有些情況下,可以使用多個空格,如果多個行需要對齊的時候(使用“=”或者”->”的時候),如下:
在括號中( 括號和中括號 (),[] ),代碼左右是不能留空格的
例外情況:在逗號的後面
GOOD:
BAD:
大括號
大括號中包含的是一個代碼塊
{:開始大括號不能單獨佔一行
}: 結束大括號必須佔一行
當大括號中只有一個命令行的時候,可以不使用大括號,但是整篇代碼大括號的使用規則要保持一致。
如下:
如果開始新的代碼塊的時候,則一定要使用新的一行作爲開始。
BAD:
賦值
在賦值的時候,使用“->”號,不要使用”=”號
GOOD:x <- 5
BAD:
x = 5
分號
當一行代碼結束的時候,不要使用分號
不要使用分號將多個命令行變成一行。(在R的代碼中,能不使用分號就不要使用分號)
3.代碼的組織
整體佈局與順序
目的:如果大家都使用相同的佈局規則,那麼閱讀他人代碼要快速和容易一些。- 版權聲明(現在是不需要的)
- 作者的聲明
- 文件的聲明,包括程序的目的,輸入和輸出
- source()和library() 的聲明(statements)
- 函數的定義
- 執行語句(such as:print,plot), 如果可行的話(這一句話可能翻譯有誤)測試單元應該專門寫在一個單獨的文件之中,命名爲originalfilename_unittest.R.(這個我可能有用)
註釋指導(Commenting Guidelines 如何寫註釋)
- 當註釋你的代碼的時候,所有的註釋都應該以#開頭,並空一個空格。
- 短註釋應該和代碼同行,而後空兩個空格,以#開頭,空一個空格,隨後寫註釋。
實例如下:
函數定義和調用
- 在定義函數寫參數的時候,要先列出沒有默認值的函數參數,隨後列出有默認值的參數。要注意先後順序。(注意前後統一) 在函數的定義和調用的時候,參數寫多行是被允許的。那麼在什麼時候要新開設一行呢?有賦值語句出現的時候(函數中有默認參數)
實例:
- Ideally, unit tests should serve as sample function calls (for shared
library routines)
如何翻譯?理想情況下,單元測試爲簡單函數調用服務(爲了共享庫的路徑)
- 在定義函數寫參數的時候,要先列出沒有默認值的函數參數,隨後列出有默認值的參數。要注意先後順序。(注意前後統一) 在函數的定義和調用的時候,參數寫多行是被允許的。那麼在什麼時候要新開設一行呢?有賦值語句出現的時候(函數中有默認參數)
(函數的說明文檔)Function Documentation
一個完整的函數應該包含相應的說明文檔。
這個說明文檔在函數定義行之後(函數體的最前面)- 一句話說明函數的作用是什麼
- 說明參數的作用,使用Args:開頭,接下來一行是一個參數,要說明參數的數據類型和參數的含義。
- 說明返回值,以Returns:開頭
總的原則是:不用看函數的代碼,就能大致明白與函數相關的必要信息。
示例:
注意: 不是所有的函數都要寫註釋,這點要記住。
- TODO style(什麼意思?之前沒見過)
Use a consistent style for TODOs throughout your code.
TODO(username): Explicit description of action to be taken
做什麼?不懂
4. 語言
Attach
不要使用Attach,它的益處遠遠小於其帶來的弊端。
在使用data.frame的時候,有時會使用Attach,這樣在調用數據的時候,可以簡化代碼。
(這個會引起不必要的麻煩,使用data.table吧)函數(Functions)
Errors should be raised using stop().
錯誤的拋出應該使用stop().**(如何使用stop?)(目標和方法)Objects and Methods
R有兩種類,S3類和S4類,原則是:能不使用S4類就儘量不使用。
5. 例外的情況
寫代碼的時候,你應該儘量遵守上面的規則,除非有更好的理由用其他的方式。
例外情況包括:別人遺留下的代碼或者修改第三方的代碼
6. 臨別贈言
使用約定俗成的規則,並且儘量保持代碼風格一致。
如果你在修改代碼,花幾分鐘看看代碼,並確定風格。原則就是你要和以後的代碼保持一致。
上面的規則只是全局規則,至於局部規則(local rule 也非常重要),要與已有代碼保持一致,不要顯得太突兀。