SIZE(25){Google's R Style Guide}
#contents
~
- コメントなどあれば。 -- &new{2009-09-01 (火) 15:08:34};
#comment
~
Rは主に統計計算、グラフィックスに使われる高水準プログラム言語です。Rプログラミングスタイルガイドの目的はRのコードを読みやすく、共有しやすく、確認しやすくすることです。以下のルールはGoogleのRユーザコミュニティで協力して作成されました。
* 概要: Rスタイルルール [#m8e7032a]
+ファイル名: 拡張子は .R
+識別子: 変数 variable.name, 関数 FunctionName, 定数 kConstantName
+一行の文字数: 最大80文字
+空白
+中括弧({}): 開き({)は同じ行に、閉じ(})はそれだけを一行に。
+代入: <-を使う。=は使わない。
+セミコロン: 使わない。
+セミコロン; 使わない。（一行にはひとつの文（式）のみということ）
+全体のレイアウトと記述順序
+コメント: #の後にスペースを入れて開始する。インラインのコメントは#の前に2個のスペースを入れる。
+関数定義と呼び出し
+関数の説明
+関数の例
+TODOのスタイル: TODO(ユーザ名)
* 概要: R言語ルール [#r263d871]
+attach: 使うな。
+関数: エラーの生成にはstop()を使うこと。
+オブジェクトとメソッド: S4オブジェクトとメソッドは可能な限り使わない。S3とS4を混ぜて使うな。
* 1.表記と命名 [#ta8c0a0c]
** ファイル名 [#wb6d246d]
ファイル名の拡張子は.Rで、意味のある名前を付けること。
GOOD: predict_ad_revenue.R
BAD: foo.R
** 識別子 [#a29f8974]
識別子にアンダースコアとハイフンを使うな。識別子は以下の規約に従って名付けること。変数名は全て小文字で、単語はドット(.)で区切る。関数名は先頭は大文字でドットは入れない (CapWords)。定数は関数と同じだけど、先頭にkを付ける。
- 変数名
GOOD: avg.clicks
BAD: avg_Clicks , avgClicks
- 関数名
GOOD: CalculateAvgClicks
BAD: calculate_avg_clicks , calculateAvgClicks
関数名は動詞にすること。~
'''例外: クラス化されたオブジェクトを作るとき、関数名(コンストラクタ)とクラスを一致させる(例えばlm)。'''
- 定数名
kConstantName
* 2.シンタックス [#n316fdc9]
** 一行の長さ [#x10765e0]
最大80文字。
** インデント [#i6b95187]
インデントには2つのスペースを用いること。タブを使ったり、タブとスペースを混ぜたりしないこと。~
'''例外: 小括弧内に改行があるとき、小括弧内の最初の文字と、それ以降の行の先頭の文字は整列させる。'''
** スペース [#p3070dde]
全ての2項演算子(=, +, -, <-など)の前後にスペースを入れること。~
'''例外: 関数呼び出しでパラメータを渡すときには、=の前後のスペースは入れても入れなくてもよい。'''
コンマの前にスペースは入れず、コンマの後に1個のスペースを入れること。
GOOD:
tabPrior <- table(df[df$daysFromOpt < 0, "campaignid"])
total <- sum(x[, 1])
total <- sum(x[1, ])
BAD:
tabPrior <- table(df[df$daysFromOpt<0, "campaignid"]) # '<'の前後にスペース
tabPrior <- table(df[df$daysFromOpt < 0,"campaignid"]) # コンマの後にスペース
tabPrior<- table(df[df$daysFromOpt < 0, "campaignid"]) # <-の前にスペース
tabPrior<-table(df[df$daysFromOpt < 0, "campaignid"]) # <-の前後にスペース
total <- sum(x[,1]) # コンマの後にスペース
total <- sum(x[ ,1]) # コンマの前ではなく後にスペース
関数呼び出し以外では、開き括弧の前にスペースを入れること。
GOOD:
if (debug)
BAD:
if(debug)
=や<-を整列するためなら、2個以上のスペースを入れてもよい。
plot(x = xCoord,
y = dataMat[, makeColName(metric, ptiles[1], "roiOpt")],
ylim = ylim,
xlab = "dates",
ylab = metric,
main = (paste(metric, " for 3 samples ", sep="")))
小括弧や大括弧の中のコードの前後にスペースは入れない。~
'''例外: コンマの後には常にスペースを入れる。'''
GOOD:
if (debug)
x[1, ]
BAD:
if ( debug ) # debugの前後にスペースは入れない。
x[1,] # コンマの後にスペース。
** 中括弧 [#n96cb8fd]
開き中括弧({)はそれ自身を一行にしないこと。閉じ中括弧はそれ自身を一行にすること。ブロックが単一の命令の時は中括弧を省いてもよいが、単一命令ブロックの時に中括弧を省くか省かないか、どちらかに統一すること。
if (is.null(ylim)) {
ylim <- c(0, 0.06)
}
あるいは (↑と↓を混ぜて使ってはいけない)
if (is.null(ylim))
ylim <- c(0, 0.06)
ブロック本体は常に新しい行で始めること。
BAD:
if (is.null(ylim)) ylim <- c(0, 0.06)
if (is.null(ylim)) {ylim <- c(0, 0.06)}
** 代入 [#f653845b]
代入には=ではなく<-を使うこと。
GOOD:
x <- 5
BAD:
x = 5
** セミコロン [#h680040e]
行の終端にセミコロンを置かない。2個以上の命令を1行に書くためにセミコロンを使わない。(セミコロンは不要で、他のGoogleスタイルガイドとの整合性のために省略されている)
* 3.コードの構成 [#cca2fb12]
** 全体のレイアウトと記述順序 [#m33c1c21]
みんなが同じレイアウトを用いれば、お互いのスクリプトをより速く、簡単に読み、理解することが出来る。
+コピーライト情報
+著者情報
+ファイルの内容(プログラムの目的、入出力の説明を含む)
+source() と library() 命令
+関数定義
+もしあれば、実行命令 (例えば print, plot)
単体テストはoriginalfilename_unittest.R(オリジナルファイル名_unittest.R)というファイル名を付けた別のファイルで行うこと。
** コメント [#j6ec5931]
コードにはコメントを。コメント行は#と1個のスペースで開始すること。
短いコメントは、コードの後に2個のスペース、#、1個のスペースを入れてから書くこと。
# Create histogram of frequency of campaigns by pct budget spent.
hist(df$pctSpent,
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)")
** 関数定義と呼び出し [#q0b104d5]
関数定義では、最初に既定値のない引数、その後に既定値のある引数をおくこと。
関数定義と関数呼び出しの両方で、一行に複数の引数を記述してよい。代入の間でのみ改行を入れてもよい。
GOOD:
PredictCTR <- function(query, property, numDays,
showPlot = TRUE)
BAD:
PredictCTR <- function(query, property, numDays, showPlot =
TRUE)
理想的には、単体テストは関数呼び出しのサンプルとして使えるようにするとよい(共有ライブラリルーチンのため)。
** 関数の説明 [#d647a66b]
関数にはコメントを。コメントセクションは関数定義の直後の行から始めること。コメントの内容は、(1)関数の説明を一文で、(2)Argsと明記してから引数の説明(データ型も)、(3)Returnsと明記してから戻り値の説明。関数のコードを読まなくても関数が使えるように、コメントには十分な説明を記述すること。
** 関数の例 [#d88f474c]
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, (もう一つのベクトル。xとyは2以上の同じ長さで欠損値は不可)
# with no missing values.
# verbose: If TRUE, prints sample covariance; if not, not. Default is TRUE. (TRUEなら共分散を出力する。既定値はTRUE)
#
# Returns:
# The sample covariance between x and y. (xとyの間の共分散)
n <- length(x)
# Error handling (エラー処理)
if (n <= 1 || n != length(y)) {
stop("Arguments x and y have invalid lengths: ", # (引数xとyの長さが不正です)
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.") # (引数xとyには欠損値は認められません)
}
covariance <- var(x, y)
if (verbose)
cat("Covariance = ", round(covariance, 4), ".\n", sep = "")
return(covariance)
}
** TODOのスタイル [#j6b08dfa]
コードの中では一貫したTODOのスタイルを用いること。
TODO(ユーザ名): 行うべきことの明確な記述
* 4. 言語 [#a09a9108]
** Attach [#qf4c0ad8]
attachは使うな。使うとエラーを起こしやすくなる。
** 関数 [#e0cbbafd]
エラーの生成にはstop()を使うこと。
** オブジェクトとメソッド [#v1c37e64]
S言語にはS3とS4というふたつのオブジェクトシステムがあり、Rでは両方とも使えます。S3はよりインタラクティブで柔軟、S4はより形式的で厳密(二つのオブジェクトシステムの説明として、Thomas Lumley著 "Programmer's Niche: A Simple Class, in S3 and S4" in R News 4/1, 2004, pgs. 33 - 36: http://cran.r-project.org/doc/Rnews/Rnews_2004-1.pdf を参考に)。
S4システムを使う強い理由がない限り、S3システムを使うこと。S4オブジェクトを使う主な理由として、そのオブジェクトをC++コードの中で直接使う場合が考えられる。S4ジェネリック/メソッドを使う主な理由として、二つの引数での多重ディスパッチが考えられる。
S3システムをS4システムを混ぜて使うな。S4メソッドはS3の継承を無視する(逆も同様)。
* 5.例外 [#k10a0cdd]
理由がない限りは、以上のスタイルを守るべき。古いコード、サードパーティのコードの変更などは、例外になり得る。
* 6.終わりに [#e3fc8415]
良識を持ち、また一貫性を保ちなさい。
もしあなたが今コードを書いているなら、少しの間コードを見渡して、スタイルを決めなさい。
もし他人がif節の前後にスペースを入れているなら、あなたもそうしなさい。
もし他人のコメントがスターで囲まれているなら、あなたもそうしなさい。
スタイルガイドに従うということは、コーディングの共通言語を持つということです。どうやって言うか、ではなく、なにを言うか、に集中することが出来るようになります。
ここで私たちがグローバルなスタイルルールを示したので、みんなが言葉を知っています。しかしローカルなスタイルもまた重要です。
もし（私たちが示したグローバルなスタイルに従って）ファイルに追加したコードが、そのまわりのコードと全然違っているようなら、その一貫性のなさによってコードを読む人が混乱してしまします。
これは避けなさい。
OK.コードの書き方についてはもう十分でしょう。
コードを書く方が遙かに楽しいでしょうから。
さあ、楽しみなさい!
* 7.参考文献 [#gfec2080]
-http://www.maths.lth.se/help/R/RCC/ - R Coding Conventions
-http://ess.r-project.org/ - emacsユーザ用。essによってRをemacsの中で走らせることができ、またRコード用のメジャーモードが入っています。
![[RjpWiki]](image/../Rlogo.png "[RjpWiki]")
