التعليقات في 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 القيم التي تحملها.