[R] R Style Guide by Hadley Wickham

해당 포스트는 Hadley Wickham이 작성한 'The tidyverse style guide' 를 번역하여 정리한 글입니다.

Lists
Intro - 0. Welcome
Analysis - 1. Files
Analysis - 2. Syntax (1)
Analysis - 2. Syntax (2)
Analysis - 3. Functions
Analysis - 4. Pipes
Analysis - 5. ggplot2
Packages - 6. Files
Packages - 7. Documentation
Packages - 8. Tests
Packages - 9. Error messages
Packages - 10. News
Packages - 11. Git/GitHub

6. 파일(Files)

분석의 파일(Analyses-Files)에 대한 대부분의 조언은 패키지의 파일(Packages-Files)에도 적용되며, 중요한 차이점은 아래 설명을 참고하시면 됩니다.

6.1 이름(Names)

파일에 단일 함수가 포함된 경우, 함수와 동일한 이름을 지정하는 것이 좋습니다.
파일에 여러 개의 관련된 함수들이 포함된 경우, 간결하지만 연상가능한 이름을 지정하는 것이 좋습니다.
더 이상 사용되지 않는 함수는 deprec- 접두사가 있는 파일에 있어야 합니다.
호환성 함수는 compat- 접두사가 있는 파일에 있어야 합니다.

6.2 구성(Organisation)

여러 기능이 포함된 파일에서는 공용 함수(public function)와 그들의 문서화(documentation)가 먼저 표시되어야 하며, 모든 문서화된 함수 뒤에 개인 함수(private function)가 표시되어야 합니다. 만약 여러 공용 함수들이 동일한 문서화(documentation)를 공유하는 경우, 모두 가까운 문서 블럭(block)은 따라야 합니다.

문서화(Documentation) : 사용자를 위해 함수(Function)에 대한 목적, 사용법 등을 정리한 내용(주석 활용)

패키지의 함수 문서화(documenting functions)에 대한 자세한 가이드는 7장(Documentation)을 참고하시면 됩니다.

# Bad
help_compute <- function() {
  # ... Lots of code ...
}

#' My public function
#'
#' This is where the documentation of my function begins.
#' ...
#' @export
do_something_cool <- function() {
  # ... even more code ...
  help_compute()
}

# Good
#' Lots of functions for doing something cool
#'
#' ... Complete documentation ...
#' @name something-cool
NULL

#' @describeIn something-cool Get the mean
#' @export
get_cool_mean <- function(x) {
  # ...
}

#' @describeIn something-cool Get the sum
#' @export
get_cool_sum <- function(x) {
  # ...
}