R의 주석: 코드에 주석 달기 (와 여러 줄 주석 처리)

# 기호

R의 주석은 #으로 시작합니다. 그 문자부터 줄 끝까지 R은 모든 것을 무시합니다.

# This whole line is a comment. R skips it.
speed_kmh <- 90

speed_ms <- speed_kmh / 3.6  # convert to meters per second

print(speed_ms)

두 가지 배치 모두 유효합니다. 주석만 있는 줄, 또는 코드 뒤에 붙는 인라인 주석입니다. 닫을 것은 없습니다. 주석은 줄이 끝나는 곳에서 그냥 끝납니다. # 하나면 충분하고, 따옴표로 감싼 문자열 안의 #은 주석이 아니라 그냥 문자입니다.

tag <- "#1 fan"  # the first # is data, this one is a comment
print(tag)

R에는 여러 줄 주석이 없습니다

모든 R 입문자가 결국 검색하는 질문의 답은 이것입니다. R에는 블록 주석 문법이 없습니다. /* ... */도, """docstring"""도, =begin/=end도 없습니다. 주석 처리할 각 줄에는 각자의 #이 필요합니다. 이는 언어의 의도된 단순함이며, 도구가 그 빈틈을 메워 주기 때문에 생각보다 불편하지 않습니다.

현실적인 해법은 편집기의 토글 단축키입니다. RStudio에서 줄들을 선택하고 Ctrl+Shift+C(Windows/Linux) 또는 Cmd+Shift+C(macOS)를 누르세요. 선택된 모든 줄 앞에 #이 붙고, 다시 누르면 사라집니다. R 프로그래머들이 하루에도 수십 번 실제로 하는 일이니, 이번 주 안에 손에 익혀 둘 만합니다. VS Code, Vim, Emacs 모두 R 파일에 대해 동일한 주석 토글 명령을 갖고 있습니다.

if (FALSE) 요령. FALSE는 결코 참이 아니므로, 코드를 if (FALSE) { ... }로 감싸면 절대 실행되지 않습니다.

if (FALSE) {
    expensive_call <- 1 / 0
    cat("you will never see this\n")
}

cat("but you will see this\n")

알아 두되 습관이 아니라 흥미로운 사실 정도로 여기세요. 실제 단점이 있기 때문입니다. 건너뛰는 코드도 여전히 문법적으로 유효한 R이어야 합니다. 진짜 블록 주석은 아무 내용이나 담을 수 있지만, 반쯤 쓰다 만 줄을 if (FALSE)로 감싸면 파싱 오류가 나서 스크립트 전체가 멈춥니다. 또한 중괄호를 잘못 편집하면 조용히 의미가 바뀝니다. 줄을 비활성화하고 싶다면 편집기 단축키가 더 안전하고, 아예 없애고 싶다면 지우세요. 버전 관리가 그러라고 있는 것입니다.

좋은 주석이 말하는 것: 무엇이 아니라 왜

코드는 이미 무엇을 하는지 말하고 있습니다. 그것을 되풀이하는 주석은 소음이며, 결국 낡아서 거짓말을 하기 시작합니다.

# Bad: narrates the obvious
x <- x + 1  # add 1 to x

# Good: explains the reason
x <- x + 1  # customer-facing IDs are 1-based, data is 0-based

두 번째 주석은 코드가 담을 수 없는 정보, 즉 그 증가가 왜 존재하는지를 전달합니다. 여러분이 쓰는 모든 주석의 시험 기준이 바로 이것입니다. 의도, 맥락, 또는 명백하지 않은 결정을 설명하는가? 주석은 이상한 줄에서 값어치를 합니다. 패키지 버그를 우회하는 코드, 의도적인 오프바이원, 특정 논문에서 가져온 수식 같은 것들입니다. 그리고 유지보수 규칙을 기억하세요. 코드를 바꾸면 주석도 바꿔야 합니다. 틀린 주석은 없느니만 못하기 때문입니다.

변수가 무엇을 담고 있는지 설명하려고 주석을 쓰고 있다면, 더 나은 해결책은 대개 더 분명한 이름입니다. 그 논의는 변수에서 다룹니다.

RStudio에서 접히는 섹션 헤더

분석 스크립트는 길어지고, 주석은 그 목차 역할을 겸합니다. RStudio는 -(또는 =나 #)가 네 개 이상으로 끝나는 주석 줄을 섹션 헤더로 인식합니다.

# Load data ----------------------------------------------------------

# Clean and reshape ----

# Model ====

각 섹션은 접을 수 있게 되고 RStudio의 문서 개요에 나타납니다. 그래서 300줄짜리 스크립트가 불러오기, 정리, 모델링, 그래프 같은 탐색 가능한 단계 목록으로 바뀝니다. 끝에 오는 문자는 네 개 이상이기만 하면 무엇이든 동작합니다. 한 가지 스타일을 골라 일관되게 쓰세요. RStudio 밖에서도 섹션 헤더 주석은 스크립트의 구조를 한눈에 보여 줍니다. 분석이 가질 수 있는 가장 값싼 문서화입니다.

roxygen2 주석: 실제 코드 속의 #'

다른 사람의 R 코드, 특히 패키지 소스를 읽다 보면 #'로 시작하는 주석을 만나게 됩니다.

#' Convert a speed from km/h to m/s
#'
#' @param kmh Speed in kilometers per hour.
#' @return Speed in meters per second.
kmh_to_ms <- function(kmh) {
    kmh / 3.6
}

이것은 roxygen2 문서화 주석입니다. 함수 정의 바로 위에 작성하면 패키지 도구가 이를 컴파일해, ?function_name으로 읽는 공식 도움말 페이지로 만들어 줍니다. 태그(@param, @return)는 함수의 입력과 출력을 설명합니다. R 자체에게 #' 줄은 평범한 주석일 뿐이며, 이 관례는 패키지 개발 도구 체계 안에서만 힘을 갖습니다. 패키지를 만들거나 자신의 함수를 본격적으로 문서화하기 전에는 직접 쓸 일이 없습니다. 지금은 패키지 소스가 낯설어 보이지 않도록 알아보기만 하면 됩니다.

핵심 정리

• #은 주석을 시작하며, 줄 전체가 주석이든 코드 뒤의 주석이든 줄 끝까지 이어집니다.
• R에는 여러 줄 주석이 없습니다. RStudio에서 Ctrl/Cmd+Shift+C로 블록을 토글하고, if (FALSE) {}는 문법적으로 유효하면서 가끔만 건너뛰는 코드에만 쓰세요.
• 무엇이 아니라 왜를 주석으로 남기고, 코드가 바뀌면 주석도 갱신하세요.
• # Section name ---- 형태의 주석은 RStudio에 접히는 섹션을 만들어 주고 읽는 사람에게 스크립트의 지도를 제공합니다.
• #' 줄은 패키지 도움말 페이지가 되는 roxygen2 문서 주석입니다.

다음 순서는 변수입니다. <-로 변수를 만들고, 이름을 잘 짓고, R이 그 값들을 어떻게 다루는지 살펴봅니다.