R'de Yorumlar: Kodunuza Yorum Yazma (ve Blokları Yorum Satırı Yapma)

# Simgesi

R'de bir yorum # ile başlar. O karakterden satırın sonuna kadar R her şeyi yok sayar:

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

Her iki yerleşim de yasaldır: kendi satırında bir yorum veya kodun ardından gelen satır içi yorum. Kapatılacak bir şey yoktur - yorum, satırın bittiği yerde biter. Tek # yeterlidir ve tırnak içindeki bir dizenin içindeki # yalnızca bir karakterdir, yorum değil:

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

R'de Çok Satırlı Yorum Yok

İşte her R acemisinin eninde sonunda Google'da arattığı sorunun yanıtı: R'de blok yorum söz dizimi yoktur. /* ... */ yok, """docstring""" yok, =begin/=end yok. Yorumlanan her satır kendi # işaretini ister. Bu, dilde bilinçli bir sadeliktir - ve kulağa geldiğinden daha az acı vericidir, çünkü boşluğu araçlar doldurur.

Gerçek dünyadaki çözüm: düzenleyicinizin geçiş kısayolu. RStudio'da satırları seçin ve Ctrl+Shift+C (Windows/Linux) veya Cmd+Shift+C (macOS) basın. Seçilen her satır # öneki alır; bir kez daha basın, kaybolurlar. R programcılarının günde onlarca kez gerçekten yaptığı şey budur ve bu hafta kas hafızanıza kazımaya değer. VS Code, Vim ve Emacs'in tümünde R dosyaları için eşdeğer yorum-geçiş komutları vardır.

if (FALSE) hilesi. FALSE asla doğru olmadığından, kodu if (FALSE) { ... } içine sarmak asla çalışmamasını garantiler:

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

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

Bilin ama alışkanlıktan çok bir merak konusu olarak görün, çünkü gerçek çekinceleri var. Atlanan kodun yine de söz dizimsel olarak geçerli R olması gerekir - gerçek bir blok yorum her şeyi tutabilir, ama yarım yazılmış bir satırın etrafındaki if (FALSE), tüm betiği durduran bir ayrıştırma hatasıdır. Süslü parantezler düzenlenirse anlamı da sessizce değişir. Satırları devre dışı bırakmak istediğinizde düzenleyici kısayolu daha güvenlidir; onları yok etmek istediğinizde silin - sürüm kontrolü bunun içindir.

İyi Yorumlar Ne Söyler: Neyi Değil, Nedenini

Kod, ne yaptığını zaten söylüyor. Bunu tekrarlayan bir yorum, eninde sonunda güncelliğini yitirip yalan söylemeye başlayacak bir gürültüdür:

# 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

İkinci yorum, kodun taşıyamayacağı bir bilgiyi taşır: artırmanın neden var olduğunu. Yazdığınız her yorumun testi budur - niyeti, bağlamı veya bariz olmayan bir kararı açıklıyor mu? Yorumlar tuhaf satırlarda hakkını verir: bir paket hatası için geçici çözüm, bilerek yapılmış bire-bir kayması, belirli bir makaleden gelen formül. Ve bakım kuralını hatırlayın: kodu değiştirdiğinizde yorumunu da değiştirin, çünkü yanlış bir yorum hiç olmamasından kötüdür.

Kendinizi bir değişkenin neyi tuttuğunu açıklayan bir yorum yazarken bulursanız, çoğu zaman daha iyi çözüm daha açık bir isimdir - bu tartışma için bkz. değişkenler.

RStudio'da Katlanan Bölüm Başlıkları

Analiz betikleri uzar ve yorumlar aynı zamanda onların içindekiler tablosudur. RStudio, dört veya daha fazla - (veya = ya da #) ile biten bir yorum satırını bölüm başlığı olarak görür:

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

# Clean and reshape ----

# Model ====

Her bölüm katlanabilir hale gelir ve RStudio'nun belge taslağında görünür; böylece 300 satırlık bir betik gezinilebilir bir adım listesine dönüşür: yükle, temizle, modelle, çiz. Sondaki karakterlerden herhangi biri, en az dört tane olduğu sürece işe yarar; bir stil seçin ve tutarlı kalın. RStudio dışında bile bölüm başlığı yorumları, bir betiğin yapısını bir bakışta görünür kılar - bir analizin sahip olabileceği en ucuz dokümantasyondur.

roxygen2 Yorumları: Doğada #'

Başkalarının R kodunu - özellikle paket kaynak kodunu - okurken #' ile başlayan yorumlarla karşılaşacaksınız:

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

Bunlar roxygen2 dokümantasyon yorumlarıdır. Bir fonksiyon tanımının hemen üstüne yazıldıklarında paket araçları tarafından, ?function_name ile okuduğunuz resmi yardım sayfalarına derlenirler. Etiketler (@param, @return) fonksiyonun girdilerini ve çıktısını tanımlar. R'nin kendisi için #' satırı sıradan bir yorumdur - geleneğin gücü yalnızca paket geliştirme araç zincirinin içindedir. Bir paket geliştirene veya kendi fonksiyonlarınızı ciddi biçimde belgeleyene kadar bunları yazmanız gerekmez; şimdilik onları tanıyın ki paket kaynak kodu gizemli görünmesin.

Buradan Ne Çıkarıyorsunuz

• # bir yorum başlatır; satır ister tamamen yorum ister kod-sonra-yorum olsun, satırın sonuna kadar sürer.
• R'de çok satırlı yorum yoktur - blokları RStudio'da Ctrl/Cmd+Shift+C ile açıp kapatın ve if (FALSE) {}'i nadiren atladığınız, söz dizimsel olarak geçerli kod için saklayın.
• Neyi değil, nedenini yorumlayın - ve kod değişince yorumları güncelleyin.
• # Section name ---- yorumları RStudio'da katlanabilir bölümler, okurlara betiğin haritasını verir.
• #' satırları, paket yardım sayfalarına dönüşen roxygen2 doküman yorumlarıdır.

Sırada: değişkenler - <- ile oluşturmak, iyi adlandırmak ve R'nin tuttukları değerlere nasıl davrandığı.