해당 포스트는 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
7. 문서(Documentation)
7.1 소개(Introduction)
미래에 코드를 사용하는 사람이 자신이 유일할 지라도 코드의 문서화(Documentation)은 필수입니다.
문서를 코드에 가깝게 유지하려면 마크다운(Markdown) 언어를 지원하는 roxygen2 패키지를 사용하는 것이 좋습니다.
7.2 제목과 설명(Title and description)
함수 문서의 첫 번째 라인을 사용하여 함수, 데이터셋, 클래스를 설명하는 간결한 제목을 제공하는 하는 것이 좋습니다.
제목은 문장을 사용해야 하지만 마침표(.)로 끝나면 안됩니다.
#' Combine values into a vector or list
#'
#' This is a generic function which combines its arguments.
#'@title 또는 @description 태그는 설명이 여러 단락이거나 글머리 기호와 같이 더 복잡한 서식을 포함하는 경우를 제외하고는 사용할 필요가 없습니다.
#' Apply a function to each element of a vector
#'
#' @description
#' The map function transform the input, returning a vector the same length
#' as the input.
#'
#' * `map()` returns a list or a data frame
#' * `map_lgl()`, `map_int()`, `map_dbl()` and `map_chr()` return
#' vectors of the corresponding type (or die trying);
#' * `map_dfr()` and `map_dfc()` return data frames created by row-binding
#' and column-binding respectively. They require dplyr to be installed.7.3 들여쓰기와 줄 바꿈(Indents and line breaks)
들여쓰기는 항상 # 다음에 한 개의 공백(one space)을 두어야 합니다. roxygen 태그에 해당하는 설명이 여러 줄에 걸쳐 있는 경우에는 두 개의 공백(two spaces)을 추가해 주어야 합니다.
#' @param key The bare (unquoted) name of the column whose values will be used
#' as column headings. 또는 여러 줄에 걸쳐 있는 태그(ex: @description, @examples, @section)는 자체 줄에 해당 태그를 갖고 그 다음 후속 줄은 들여쓰지 않아도 됩니다.
#' @examples
#' 1 + 1
#' sin(pi) 필요한 경우에는 @section 전후에 줄 바꿈(line breaks)을 사용하는 것이 좋습니다.
#' @section Tidy data:
#' When applied to a data frame, row names are silently dropped. To preserve,
#' convert to an explicit variable with [tibble::rownames_to_column()].
#'
#' @section Scoped filtering:
#' The three [scoped] variants ([filter_all()], [filter_if()] and
#' [filter_at()]) make it easy to apply a filtering condition to a
#' selection of variables.7.4 문서화 파라미터(Documenting parameters)
@param, @seealso, @return와 같은 대부분의 태그의 경우 텍스트는 대문자로 시작하여 마침표(full stop)로 끝나는 문장이어야 합니다.
#' @param key The bare (unquoted) name of the column whose values will be used
#' as column headings. 만약 일부 함수들이 파라미터를 공유하는 경우, @inheritParams를 사용하여 여러 위치에서 컨텐츠가 중복되지 않도록 할 수 있습니다.
#' @inheritParams function_to_inherit_from7.5 대문자와 마침표(Capitalization and full stops)
모든 글머기 기호(bullets), 열거형(enumerations), 인수 설명(argument descriptions) 등에 대해서는 문장을 사용하고 각 단어의 끝에 마침표를 사용하시면 됩니다.
R의 경우 대소문자를 구분하므로 함수 이름 또는 패키지에 대문자를 사용하면 않되며 열거 또는 글머리 기호 목록 앞에 콜론을 사용하시는게 좋습니다.
#' @details
#' In the following, we present the bullets of the list:
#' * Four cats are few animals.
#' * forcats is a package.7.6 교차 결합(Cross-linking)
R의 도움말 파일 시스템과 외부 리소스 모두에서 상호 참조(Croess-referencing)가 권장 됩니다.@seekals에 밀접하게 관련된 함수들을 나열하시면 되며, 관련된 단일 함수는 문장으로 사용할 수 있습니다.
#' @seealso [fct_lump()] to automatically convert the rarest (or most common)
#' levels to "other".더 많은 권고사항을 글머리표 목록(bulleted list)에 정리하는 것이 좋습니다.
#' @seealso
#' * [tibble()] constructs from individual columns.
#' * [enframe()] converts a named vector into a two-column tibble (names and
#' values).
#' * [name-repair] documents the details of name repair.만약 관련 함수 그룹(family)이 있는 경우, @family 태그를 사용하여 적절한 리스트와 관련 함수를 @sea 섹션에 자동으로 추가할 수 있으며 그룹(family) 이름은 복수형 입니다.dplyr에서 동사는 arrange(), filter(), mutate(), slice(), summarize()을 통해 단일 테이블 동사의 그룹(family)을 형성할 수 있습니다.
#' @family single table verbs외부 리소스에 연결할 때, 전체 URL을 <>와 함께 인라인으로 포함하거나 주변 산문(prose) 및 링크 텍스트로 하이퍼 링크(hyperlink)가 어디로 가는지 명확하게 해야 합니다. "click here" 와 같은 텍스트 사용은 추천하지 않습니다.
7.7 R 코드(R Code)
유효한 R 코드가 포함된 텍스트는 백틱(backticks)을 사용하여 표시해야 합니다. 다음을 참고하세요.
- 함수 이름(Function names) :
tibble() - 함수 인수(Function arguments) :
na.rm - 값(Values) :
TRUE,FALSE,NA,NaN,...,NULL - 리터럴 R코드(Literal R code) :
mean(x, na.rm = TRUE) - 클래스 이름(Class names) :
tbl_df
패키지 이름에는 코드 글꼴(code font)을 사용을 추천하지 않습니다. 패키지 이름이 문맥(context)에서 애매한 경우, "foo 패키지"와 같은 단어를 사용하여 차이를 나타내는 것이 좋습니다. 만약 문장의 시작 부분에서 사용해야 한다면 함수 이름을 대문자로 표시하지 않아야 합니다.
7.8 내부 기능(Internal functions)
내부 기능(Internal functions)은 평소와 같이 # 주석과 함께 문서화해야 합니다. .Rd 파일이 생성되는 것을 방지하려면 @noRd 태그를 사용하시면 됩니다.
#' Drop last
#'
#' Drops the last element from a vector.
#'
#' @param x A vector object to be trimmed.
#'
#' @noRd출처
[1] The tidyverse style guide
[2] R package - roxygen2
[3] Why Your Links Should Never Say “Click Here”
