Chú thích trong R: cách comment code và nhiều dòng một lúc

Ký hiệu

Chú thích (comment) trong R bắt đầu bằng #. Từ ký tự đó đến cuối dòng, R bỏ qua tất cả:

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

Cả hai vị trí đều hợp lệ: một chú thích nằm riêng trên một dòng, hoặc một chú thích cùng dòng đứng sau code. Không có gì cần đóng lại: chú thích đơn giản là kết thúc ở cuối dòng. Một dấu # là đủ, và # bên trong một chuỗi đặt trong dấu ngoặc kép chỉ là một ký tự, không phải chú thích:

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

R không có chú thích nhiều dòng

Đây là câu trả lời cho câu hỏi mà mọi người mới học R sớm muộn cũng tìm trên Google: R không có cú pháp chú thích khối. Không có /* ... */, không có """docstring""", không có =begin/=end. Mỗi dòng chú thích cần một # riêng. Đây là sự đơn giản có chủ ý của ngôn ngữ, và nó đỡ phiền hơn bạn tưởng, vì các công cụ đã lấp khoảng trống đó.

Giải pháp thực tế: phím tắt bật/tắt chú thích của trình soạn thảo. Trong RStudio, chọn các dòng và nhấn Ctrl+Shift+C (Windows/Linux) hoặc Cmd+Shift+C (macOS). Mọi dòng được chọn sẽ có # ở đầu; nhấn lại lần nữa và chúng biến mất. Đây là điều lập trình viên R thực sự làm, hàng chục lần mỗi ngày, và rất đáng để luyện thành phản xạ ngay trong tuần này. VS Code, Vim và Emacs đều có lệnh bật/tắt chú thích tương đương cho tệp R.

Mẹo if (FALSE). Vì FALSE không bao giờ đúng, bọc code trong if (FALSE) { ... } đảm bảo đoạn code đó không bao giờ chạy:

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

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

Hãy biết mẹo này, nhưng coi nó là một điều thú vị chứ đừng biến thành thói quen, vì nó có những hạn chế thật sự. Đoạn code bị bỏ qua vẫn phải là R hợp lệ về cú pháp: một chú thích khối thật sự có thể chứa bất cứ thứ gì, nhưng if (FALSE) bọc quanh một dòng viết dở là lỗi phân tích cú pháp làm dừng cả script. Ý nghĩa của nó cũng âm thầm thay đổi nếu các dấu ngoặc nhọn bị sửa. Khi bạn muốn vô hiệu hóa vài dòng, phím tắt của trình soạn thảo an toàn hơn; khi bạn muốn chúng biến mất, hãy xóa đi, đó là việc của hệ thống quản lý phiên bản.

Chú thích tốt nói gì: vì sao, không phải cái gì

Code đã tự nói nó làm gì. Một chú thích lặp lại điều đó chỉ là nhiễu, rồi sớm muộn sẽ lỗi thời và bắt đầu nói sai:

# 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

Chú thích thứ hai mang thông tin mà code không thể hiện được: vì sao phép cộng thêm đó tồn tại. Đó là phép thử cho mọi chú thích bạn viết: nó có giải thích ý định, bối cảnh hay một quyết định không hiển nhiên không? Chú thích phát huy giá trị ở những dòng kỳ lạ: cách xử lý tạm cho một bug của package, phép lệch một đơn vị có chủ ý, công thức lấy từ một bài báo cụ thể. Và hãy nhớ quy tắc bảo trì: khi sửa code, hãy sửa cả chú thích của nó, vì một chú thích sai còn tệ hơn không có chú thích.

Nếu bạn thấy mình phải viết chú thích để giải thích một biến chứa gì, thường thì cách sửa tốt hơn là một cái tên rõ ràng hơn; xem biến để hiểu lập luận đó.

Tiêu đề mục thu gọn được trong RStudio

Script phân tích ngày càng dài, và chú thích kiêm luôn vai trò mục lục. RStudio coi một dòng chú thích kết thúc bằng bốn ký tự - trở lên (hoặc = hay #) là tiêu đề mục:

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

# Clean and reshape ----

# Model ====

Mỗi mục trở nên thu gọn được và xuất hiện trong phần dàn ý tài liệu của RStudio, nên một script 300 dòng biến thành một danh sách các bước dễ điều hướng: nạp, làm sạch, mô hình, vẽ biểu đồ. Ký tự nào ở cuối cũng được, miễn là có ít nhất bốn ký tự; hãy chọn một kiểu và giữ nhất quán. Ngay cả ngoài RStudio, chú thích tiêu đề mục cũng giúp nhìn thấy cấu trúc của script trong nháy mắt: đó là dạng tài liệu rẻ nhất mà một bài phân tích có thể có.

Chú thích roxygen2: #' trong thực tế

Khi đọc code R của người khác, đặc biệt là mã nguồn package, bạn sẽ gặp những chú thích bắt đầu bằng #':

#' 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
}

Đây là các chú thích tài liệu roxygen2. Được viết ngay phía trên định nghĩa hàm, chúng được công cụ làm package biên dịch thành các trang trợ giúp chính thức mà bạn đọc bằng ?function_name. Các thẻ (@param, @return) mô tả đầu vào và đầu ra của hàm. Với chính R, một dòng #' là chú thích bình thường: quy ước này chỉ có tác dụng bên trong bộ công cụ phát triển package. Bạn chưa cần viết chúng cho đến khi xây dựng một package hoặc viết tài liệu nghiêm túc cho các hàm của mình; hiện tại, chỉ cần nhận ra chúng để mã nguồn package không còn bí ẩn.

Những điều cần nhớ

• # bắt đầu một chú thích; nó kéo dài đến cuối dòng, dù cả dòng là chú thích hay code rồi đến chú thích.
• R không có chú thích nhiều dòng: bật/tắt chú thích cho cả khối bằng Ctrl/Cmd+Shift+C trong RStudio, và chỉ dùng if (FALSE) {} cho code hợp lệ về cú pháp mà bạn hiếm khi bỏ qua.
• Chú thích vì sao, không phải cái gì, và cập nhật chú thích khi code thay đổi.
• Chú thích dạng # Section name ---- cho RStudio các mục thu gọn được và cho người đọc một bản đồ của script.
• Các dòng #' là chú thích tài liệu roxygen2, sẽ trở thành trang trợ giúp của package.

Tiếp theo: biến, cách tạo biến bằng <-, đặt tên biến cho tốt, và cách R xử lý các giá trị mà biến chứa.