הערות ב-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 הערה מרובת שורות: החליפו מצב של בלוקים עם Ctrl/Cmd+Shift+C ב-RStudio, ושמרו את if (FALSE) {} לקוד תקין תחבירית שמדלגים עליו לעיתים רחוקות.
• כתבו בהערה את הלמה, לא את המה, ועדכנו הערות כשהקוד משתנה.
• הערות בסגנון # Section name ---- נותנות ל-RStudio מקטעים מתקפלים ולקוראים מפה של הסקריפט.
• שורות #' הן הערות תיעוד של roxygen2 שהופכות לדפי עזרה של חבילות.

הבא בתור: משתנים. איך יוצרים אותם עם <-, איך נותנים להם שמות טובים, ואיך R מתייחסת לערכים שהם מחזיקים.