GoogleでのRコーディングスタイル

前回の「GoogleとFacebookではRはどのように使われているか？」が意外と人気だったため、引き続き統計ソフトRのお話。

今回取り上げるのは、GoogleでのRコーディングスタイルについて。
これもちょっと調べ物をしていた際に発見したページです。
（もしかしたら、Rを利用されている方にとってはポピュラーなページかもしれませんが）

今回もこちらのページを日本語訳に挑戦してみました。
（例によって英訳に誤訳等があるかもしれません…ご容赦ください）

GoogleでのRコーディングスタイル

今回のページはこちら。
GoogleCodeの中のページです。元々はGoogleCodeの中で、各種言語のコーディングスタイルが記載されているようです。
C++や、Objective-C、Pythonのスタイルが書いてありました。

Google's R Style Guide

サマリー：Rスタイルルール

1.ファイル名：「.R」で終わること
2.アイデンティティ：変数.名前、関数名、定数
3.一行の文字数：最大80文字
4.インデント：2つのスペース。タブは使わない
5.スペースの取り方
6.中括弧（{} ←これの事！知らなかった。Curly Bracesっていうんですね）
7.代入：「<- 」を利用しましょう。「＝」じゃなくて。
8.セミコロン：使っちゃダメ
9.一般的な表記
10.コメントガイドライン：すべてのコメントは「＃」の後にスペースを入れる。インラインは「＃」の前にスペース２つ
11.関数の定義と呼び出し
12.関数のドキュメント
13.関数例
14.ToDo例

サマリー：R言語のルール

1. attach:使用を避ける。
2.関数：エラーはstop()を利用して表示させる。
3.オブジェクトとメソッド：可能であれば、S4オブジェクトとメソッドは使用を避ける。S3とS4は混ぜて利用しない。

表記法とネーミング

・ファイル名
ファイル名は「.R」で終わり、意味がわかるように命名をする。
[ファイル名]
良い例：predict_ad_revenue.R
悪い例：foo.R

・アイデンティティ
「＿」（アンダースコア）や「ー」（ハイフン）は利用しない。アイデンティティは以下の慣例にしたがって利用する。
変数名はすべて小文字で、「.」（ドット」は利用して意味をつける。関数名は先頭を大文字にしてドットを利用しない。
定数は関数と同様に表記して最初に「k」を入れる。
[変数]
良い例：avg.clicks
悪い例：avg_Clicks , avgClicks
[関数名]
良い例：CalculateAvgClicks
悪い例：calculate_avg_clicks , calculateAvgClicks
[定数名]
kConstantName

シンタックス

・一行の文字数
最大でも1行80文字

・インデント
コードにインデントを入れる場合、2つのスペースを入れる。タブやタブとスペースを混ぜたものは利用しない。

・空白
スペースは、すべてのバイナリオペレータ(=, +, -, <-, ほか.)の周りで利用する。 　コンマの前にはスペースは入れずに、コンマの後にスペースを入れる。
良い例：tabPrior <- table(df[df$daysFromOpt < 0, "campaignid"])
total <- sum(x[, 1])
total <- sum(x[1, ]) 　
悪い例：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]) # コンマの前にスペースが必要 　

左辺の前にスペースを入れる。（関数呼び出し以外） 　
良い例：if (debug) 　
悪い例：if(debug)

イコールやアロー（<-)が改善するのであれば、１行に他のスペースの入れるのも問題なし。 　

plot(x    = xCoord,
     y    = dataMat[, makeColName(metric, ptiles[1], "roiOpt")],
     ylim = ylim,
     xlab = "dates",
     ylab = metric,
     main = (paste(metric, " for 3 samples ", sep=""))) 

) 　
※見やすくなれば、スペースは入れても問題なし。 　

カッコやブラケットの周りにはスペースはいれてはならない。
例外：コンマの後にスペースを入れる。 　
良い例：if (debug)
x[1, ] 　
悪い例：if ( debug ) # "debug"の周りにはスペースを入れない 　　　　
x[1,] # コンマの後にはスペースを入れる。

・中括弧
中括弧の開始はそれ単体で始めてはならない。終了の中括弧はそれだけで１行にしておく。１行で構成される場合は中括弧は覗いてもよい。

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

xor (but not both)

if (is.null(ylim)) 

ylim <- c(0, 0.06)

ブロック本体は新しい行で開始されなければならない。 　
悪い例：if (is.null(ylim)) ylim <- c(0, 0.06)　#中括弧を入れる 　　　　　
if (is.null(ylim)) {ylim <- c(0, 0.06)} #改行を入れる 　


・代入
「<-」を利用。「＝」は利用しない。 　
良い例：x <- 5 　#「<-」を利用している。 　
悪い例：x = 5　#「＝」を利用している。

  ・セミコロン
セミコロンで終わらせてはいけないし、１つのコマンドを同じ行に利用する場合は、セミコロンは省略してはならない。
（セミコロンは必要ではありませんし他のGoogleスタイルガイドでも省略されています）

構成

・一般的なレイアウトと順番
みなさんが統一された順番でコードを書くと、私たちは、お互いのコード（スクリプト）を早くそしてより簡単に理解することができます。
1.　著作権コメント
2.　作者コメント
3.　プログラムの目的、インプット、アウトプットを含めたファイルの詳細コメント、
4.　source()、library()ステートメントを記入
5.　関数の定義
6.　print ,plotなどの実行するステートメント

単体テストを行う場合は、originalfilename_unittest.Rのように別ファイルにすること。

・コメントガイドライン
コメントをコードに書いてください。すべてのコメントは「#」の後にスペースで書いてください。
短いコメントはコードの後ろに２つスペースを入れ、「#」の後に１つスペースを入れてください。

# 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)")

・関数の定義と呼び出し
関数の定義は、デフォルト値以外を最初に持ってきて、その後にデフォルト値を持ってくる。
関数の定義と呼び出しを両方行う場合、複数行にわたってもよい。改行は代入の場合に許される。
良い例：PredictCTR <- function(query, property, numDays, 　　　　
showPlot = TRUE) # 代入を行っているため、改行してもよい。 　
悪い例：PredictCTR <- function(query, property, numDays, showPlot = TRUE)# 代入で改行されていない。
原則的に、単体テストはサンプル関数で呼び出されるべきである。 


・関数のドキュメント
関数のドキュメントは関数の定義のすぐ上にコメントを書いた方がよい。これらのコメントは１センテンスで構成差れるべきで「Args：」で説明したほうがよい。日付を含む返り値は「Returns:」で説明したほうがよい。
コメントは他の利用者から関数コードを見なくても使えるように十分に書く必要がある。

・関数のサンプルコード

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 invalid 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リストは書いてください。

言語

・Attach
attachを利した場合、大量のエラーを生成する場合があります。利用は避けてください。

・関数
エラーを発生させる場合は、stop()関数でエラーを表示させてください。

・オブジェクトとメソッド
S言語は２つのオブジェクトシステムを持っていて、両方ともRでは利用できます。
S3メソッドはインタラクティブで柔軟ですが、S4はフォーマルで厳格です。

S4オブジェクトを利用する強い理由がない限り、S3オブジェクトを利用してください。
S4オブジェクトを利用する際の第一の理由はC++コードを直接利用する場合です。
S3とS4を混ぜて使うのは避けてください。S4メソッドはS3の資産無視します。そのまた逆も同じです。

例外

他に合理的な理由がない限りはコーディングスタイルは上記に従うべきです。
例外は、古いコードや３rdパーティーのコードに含まれます。

最後に

コードを書く際は、一般常識と一貫性を使ってください。
もしコードを書く場合、数分間を使って、コード周りを見渡してあなたのコーディングスタイルを決めてください。
もし他の方がif文の回りにスペースを利用していた場合、それに従ってください。また、他の方がコメントに星を利用していた場合、あなたも同様にしてください。

スタイルガイドラインのポイントは、コードを書く人があなたが何をいわんとしているか、さらにどうやって実現するかを理解させ、集中させるための共通の用語です。私たちは、共通の用語を知る人のためスタイルルールを提供しました。
しかし、ローカルスタイルは同様に重要です。もしあなたが追加しようとするファイルのコーディングスタイルが大幅に違う場合、（コードスタイルの）不連続性は、コードを読むときにリズムを崩します。これは避けてください。

コードを書くためのスタイルはこれで十分です。コード自体は非常に面白いです。
楽しんで！

リファレンス

http://www.maths.lth.se/help/R/RCC/ - R Coding Conventions
http://ess.r-project.org/ - For emacs users. This runs R in your emacs and has an emacs mode.

書き終わって

このブログが始まって以来，最大の長さになってしまいました。
これからRを勉強しようとされる人（私も含めて）にとって参考になればと思います。