関数の使い方は内側に書く

R の関数を書くときには、使い方などのコメントを関数の内側に書くと便利です。

R で関数オブジェクトを呼び出すと、その関数のソースコードが表示されます。例えば、次のような関数があったとします。

# 引数同士を足し合わせる。
#
# 引数：
#   a : 足される数
#   b : 足す数
# 戻り値：
#   a と b を足し合わせた数
add <- function(a, b) {
    # 計算結果を返す
    return(a + b)
}

この関数オブジェクトを次のように呼び出すと、次のように関数のソースコードが表示されます。（「>」はプロンプトです）

> add
function(a, b) {
    # 計算結果を返す
    return(a + b)
}

ここで、関数の使い方を記した関数外部のコメントは消えていますが、内部のコメントは残っていることに気づきます。

そこで、関数の使い方を関数内部に入れてしまいます。

add <- function(a, b) {
# 引数同士を足し合わせる。
#
# 引数：
#   a : 足される数
#   b : 足す数
# 戻り値：
#   a と b を足し合わせた数

    # 計算結果を返す
    return(a + b)
}

このようにすると、関数オブジェクトを呼び出したときに関数の使い方も分かって便利です。

> add
function(a, b) {
# 引数同士を足し合わせる。
#
# 引数：
#   a : 足される数
#   b : 足す数
# 戻り値：
#   a と b を足し合わせた数

    # 計算結果を返す
    return(a + b)
}

（；^ω^）これまでは、Java などの癖で関数定義の上に書いていました。ところがある日、関数内部のコメントが残っていることに気づき、R の関数のコメントは関数内部に書くようにしました。