R的編碼風格指南

概要: R編碼風格約定

1. 文件命名: 以.R(大寫)結尾

2. 標識符命名: variable.name, FunctionName, kConstantName

3. 單行長度: 不超過80個字符

4. 縮進: 兩個空格, 不使用製表符

5. 空白

6. 花括號: 前括號不折行寫, 後括號獨佔一行

7. else語句: 用花括號包圍

8. 賦值符號: 使用<-, 而非=

9. 分號: 不要用

10. 整體佈局和順序

11. 註釋準則: 全部註釋以#開始, 後接一個空格; 行內註釋須要在#前加兩個空格

12. 函數的定義和調用

13. 函數文檔

14. 示例函數

15. TODO書寫風格: TODO(用戶名)

 

概要: R語言使用規則

1. attach: 避免使用

2. 函數: 錯誤(error)應當使用stop()拋出

3. 對象和方法: 儘量避免使用S4對象和方法; 永遠不要混用S3和S4

 

表示和命名

文件命名

    文件名應以.R(大寫)結尾, 文件名自己要有意義. 

    正例: predict_ad_revenue.R

    反例: foo.R

標識符命名

    在標識符中不要使用下劃線(_)或連字符(-). 標識符應根據以下慣例命名. 變量名應使用點(.)分隔全部的小寫字母或單詞; 函數名首字母大寫, 不用點分隔(所含單詞首字母大寫); 常數命名規則同函數, 但需使用一個k開頭.

    variable.name

        正例: avg.clicks

        反例: avg_Clicks, avgClicks

    FunctionName

        正例: CalculateAvgClicks

        反例: calculate_avg_clicks, calculateAvgClick

        函數命名應爲動詞或動詞性短語. 

        例外: 當建立一個含類(class)屬性的對象時, 函數名(也是constructor)和類名(class)應當匹配(例如, lm).

    kConstantName

語法

    單行長度

        最大單行長度爲80個字符. 

縮進

    使用兩個空格來縮進代碼. 永遠不要使用製表符或混合使用兩者. 

    例外: 當括號內發生折行時, 所折行與括號內的第一個字符對齊. 

 

空白

    在全部二元操做符(=, +, -, <-等等)的兩側加上空格. 

    例外: 在函數調用中傳遞參數時=兩邊的空格可加可不加. 

    不可在逗號前加空格, 逗號後總須加空格.

    正例: 

?

1 2 3

tab.prior <- table(df[df$days.from.opt <  0 ,  "campaign.id" ]) total <- sum(x[,  1 ]) total <- sum(x[ 1 , ])

    反例: 

?

1 2 3 4 5 6

tab.prior <- table(df[df$days.from.opt< 0 ,  "campaign.id" ])  # 在 '<' 兩側須要增長空格 tab.prior <- table(df[df$days.from.opt <  0 , "campaign.id" ])  # 逗號後須要一個空格 tab.prior<- table(df[df$days.from.opt <  0 ,  "campaign.id" ])  # 在<-前須要一個空格 tab.prior<-table(df[df$days.from.opt <  0 ,  "campaign.id" ])  # 在<-兩側須要增長空格 total <- sum(x[, 1 ])  # 逗號後須要一個空格 total <- sum(x[ , 1 ])  # 逗號後須要一個空格, 而非逗號以前

    在前括號前加一個空格, 函數調用時除外. 

    正例:

?

1	if  (debug)

    反例: 

?

1	if (debug)

    多加空格(好比在行內使用多於一個空格)也是能夠的, 若是這樣作可以改善等號或箭頭(<-)的對齊效果. 

?

1 2 3 4 5 6

plot(x    = x.coord,       y    = data.mat[, MakeColName(metric, ptiles[ 1 ],  "roiOpt" )],       ylim = ylim,       xlab =  "dates" ,       ylab = metric,       main = (paste(metric,  " for 3 samples " , sep =  "" )))

    不要向圓括號或方括號中的代碼兩側加入空格. 

    例外: 逗號後總須加空格. 

    正例:

?

1 2	if  (debug) x[ 1 , ]

    反例: 

?

1 2	if  ( debug )  # debug的兩邊不要加空格 x[ 1 ,]  # 須要在逗號後加一個空格

花括號

    前括號永遠不該該獨佔一行; 後括號應當老是獨佔一行. 您能夠在代碼塊只含單個語句時省略花括號; 但在處理這類單個語句時, 您必須先後一致地要麼所有使用花括號, 或者所有不用花括號. 

?

1 2 3

if  (is. null (ylim)) {    ylim <- c( 0 ,  0.06 ) }

    或(不可混用)

?

1 2	if  (is. null (ylim))    ylim <- c( 0 ,  0.06 )

    總在新起的一行開始書寫代碼塊的主體. 

    反例: 

?

1 2	if  (is. null (ylim)) ylim <- c( 0 ,  0.06 ) if  (is. null (ylim)) {ylim <- c( 0 ,  0.06 )}

 

用花括號包圍else語句

    else語句應該用花括號在同一行包圍起來.

    正例:

?

1 2 3 4 5

if  (condition) {    one or more lines }  else  {    one or more lines }

    反例:

?

1 2 3 4 5 6

if  (condition) {    one or more lines } else  {    one or more lines }

    反例:

?

1 2 3 4

if  (condition)    one line else    one line

 

賦值

    使用<-進行賦值, 不用=賦值. 

    正例: 

?

1

x <-  5

    反例: 

?

1

x =  5

分號

    不要以分號結束一行, 也不要利用分號在同一行放多於一個命令. (分號是毫無必要的, 而且爲了與其餘Google編碼風格指南保持一致, 此處一樣略去. )

 

代碼組織

    整體佈局和順序

        若是全部人都以相同順序安排代碼內容, 咱們就能夠更加輕鬆快速地閱讀並理解他人的腳本了.  

            1. 版權聲明註釋

            2. 做者信息註釋

            3. 文件描述註釋, 包括程序的用途, 輸入和輸出

            4. source()和library()語句

            5. 函數定義 

            6. 要執行的語句, 若是有的話(例如, print, plot)

        單元測試應在另外一個名爲原始的文件名_unittest.R的獨立文件中進行. 

 

    註釋準則

        註釋您的代碼. 整行註釋應以#後接一個空格開始.

        行內短註釋應在代碼後接兩個空格, #, 再接一個空格. 

?

1 2 3 4 5 6

# Create histogram of frequency of campaigns by pct budget spent. hist(df$pct.spent,       breaks =  "scott" ,  # method  for  choosing number of buckets       main   =  "Histogram: fraction budget spent by campaignid" ,       xlab   =  "Fraction of budget spent" ,       ylab   =  "Frequency (count of campaignids)" )

 

    函數的定義和調用

        函數定義應首先列出無默認值的參數, 而後再列出有默認值的參數. 

        函數定義和函數調用中, 容許每行寫多個參數; 折行只容許在賦值語句外進行. 

        正例: 

?

1	PredictCTR <- function(query, property, numDays, showPlot = TRUE)

        反例: 

?

1 2	PredictCTR <- function(query, property, num.days, show.plot =                         TRUE)

        理想狀況下, 單元測試應該充當函數調用的樣例(對於包中的程序來講). 

 

    函數文檔

        函 數在定義行下方都應當緊接一個註釋區. 這些註釋應當由以下內容組成: 此函數的一句話描述; 此函數的參數列表, 用Args: 表示, 對每一個參數的 描述(包括數據類型); 以及對於返回值的描述, 以Returns: 表示. 這些註釋應當描述得足夠充分, 這樣調用者無須閱讀函數中的任何代碼便可 使用此函數. 

 

    示例函數

?

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

CalculateSampleCovariance <- function(x, y, verbose = TRUE) {    # Computes the sample covariance between two vectors.    #    # Args:    #   x: One of two vectors whose sample covariance is to be calculated.    #   y: The other vector. x and y must have the same length, greater than one,    #      with no missing values.    #   verbose: If TRUE, prints sample covariance;  if  not, not. Default is TRUE.    #    # Returns:    #   The sample covariance between x and y.    n <- length(x)    # Error handling    if  (n <=  1  || n != length(y)) {      stop( "Arguments x and y have different lengths: " ,           length(x),  " and " , length(y),  "." )    }    if  (TRUE %in% is.na(x) || TRUE %in% is.na(y)) {      stop( " Arguments x and y must not have missing values." )    }    covariance <- var(x, y)    if  (verbose)      cat( "Covariance = " , round(covariance,  4 ),  ".\n" , sep =  "" )    return (covariance) }

 

    TODO書寫風格

        編碼時通篇使用一種一致的風格來書寫TODO. 

        TODO(用戶名): 所要採起行動的明確描述

 

語言 

    Attach

        使用attach形成錯誤的可能數不勝數. 避免使用它. 

 

    函數

        錯誤(error)應當使用stop()拋出. 

 

    對象和方法

        S 語言中有兩套面向對象系統, S3和S4, 在R中這兩套都可使用. S3方法的可交互性更強, 更加靈活, 反之, S4方法更加正式和嚴格. (對這 兩套系統的說明, 參見ThomasLumley的文 章"Programmer'sNiche: ASimpleClass, inS3andS4", 發表於RNews4/1, 2004, 33-36 頁: http://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf. 

        這裏推薦使用S3對象和方法, 除非您有很強烈的理由去使用S4對象和方法. 使用S4對象的一個主要理由是在C++代碼中直接使用對象. 使用一個S4泛型/方法的主要理由是對雙參數的分發.     

        避免混用S3和S4: S4方法會忽略S3中的繼承, 反之亦然. 

        例外: 除非有不去這樣作的好理由, 不然應當遵循以上描述的編碼慣例. 例外包括遺留代碼的維護和對第三方代碼的修改. 

 

結語

    遵照常識, 先後一致. 

    若是您在編輯現有代碼, 花幾分鐘看看代碼的上下文並弄清它的風格. 若是其餘人在if語句周圍使用了空格, 那您也應該這樣作. 若是他們的註釋是用星號組成的小盒子圍起來的, 那您也要這樣寫。

遵 循編碼風格準則的意義在於, 人們至關於有了一個編程的通用詞彙表, 因而人們能夠專一於您在說什麼, 而不是您是怎麼說的. 咱們在這裏提供全局的編碼 風格規則以便人們瞭解這些詞彙, 但局部風格也很重要. 若是您加入文件中的代碼看起來和周圍的已有代碼大相徑庭, 那麼代碼閱讀者的閱讀節奏就會被破 壞. 儘可能避免這樣作. OK, 關於如何寫代碼已經寫得夠多了; 代碼自己要有趣的多. 編碼愉快!

 

參考文獻

    http://www.maths.lth.se/help/R/RCC/ - R語言編碼慣例

    http://ess.r-project.org/ - 爲emacs用戶而生. 在您的emacs中運行R而且提供了一個emacsmode.