sdj_raising_your_code_to_professional_standards
1.0.0
هذه هي النسخة الخشنة من المقال المنشور في sdjournal ، على https://sdjournal.org/raising-code-professional-shandards. مقالتي في القسم الحر ويمكنك الاشتراك مع حساب GitHub.
تريد أن تكون جيدًا. تريد أن تتعلم كتابة حزمة تتبع جميع إرشادات الخبراء. أنت منفتح على تصحيحه بواسطة أي أداة مهنية وتعلم منها. تريد برمجة مثل الايجابيات. تريد إنشاء حزمة تفخر بها.
ثم يجب عليك قراءة هذا المقال.
سوف تتعلم إضافة اختبار تلقائي لترميز وتغطية الرمز والممارسات الجيدة. يتم تشغيل كل هذا بواسطة git دفع الأمر الذي يقوم بتحميل رمز الحزمة إلى github.
سنستخدم حزمة مثال كحالة اختبار.
في النهاية ، سيكون لديك نص يجبرك على العمل مثل المحترف.
من المفترض أنك تعرف كيف
في حال لم تتمكن بعد من قراءة وظيفة R ، أوصي بقراءة [Matloff ، 2011] أو استخدام حزمة "الدوامة".
في حال لم تتمكن من كتابة حزمة أو استخدام TestThat أو معرفة Github ، أوصي القراءة [Hadley ، 2015].
أنا أستمتع بتدريس البرمجة بعد أعلى المعايير في الصناعة. يواجه طلابي ، الذين تتراوح أعمارهم بين 7 و 77 عامًا ، اقتباسات من المشورة من الأدب ، وخاصة من "المبرمج العملي" من تأليف أندرو هانت وديفيد توماس. فيما يتعلق R ، أود أن أقتبس من كل النصائح من هادلي ويكهام.
اتباع الممارسات الجيدة للخبراء سيوفر الوقت في تطوير التعليمات البرمجية.
يتبع إعداد هذه المقالة بعض هذه الممارسات الجيدة. الممارسات هي معيار ترميز عقلاني ، وله تغطية عالية الكود (يتم اختبار جميع التعليمات البرمجية) ، واستخدم R بطريقة عملية.
في هذه المقالة ، سأوضح كيف يساعد الخبراء.
أولاً ، سأقدم الحزمة "PRDE" ("مثال تطوير R Professional R"). تعمل هذه الحزمة كحالة اختبار لإظهار كيفية تعرض عيوبها من خلال إعداد هذه المقالة. وبالتالي فإن الحزمة معيب عن قصد ، ومع ذلك يجتاز جميع اختبارات القبش. يتم استضافة "PRDR" على جيثب.
ثم أوضح كيفية إعداد حسابات على مواقع الويب التي ستتفاعل بسلاسة مع حساب GitHub. هذه هي Travis CI ، لإنشاء اختبار تلقائي (المزيد حول ذلك لاحقًا) ، و Codecov الذي يتتبع تغطية رمز الحزمة (المزيد حول ذلك لاحقًا).
بعد تنشيط جميع مواقع الويب ، يتم تحميل ملف إلى GitHub الخاص بالحزمة ، والذي سيؤدي إلى استجابات من خلال موقع Travis CI و Codecov. سأناقش هذه الردود واحدة تلو الأخرى.
حالة الاختبار عبارة عن حزمة تسمى "PRDE" ، والتي تتبع الهيكل الموضح في [Wickham ، 2015]. يتم استضافة الحزمة على جيثب:
الشكل 1. جيثب الحزمة "prde"
ضمن حزمة "prde" توجد وظيفة ، تسمى do_magic ، مثل هذا:
#' Multiplies all values by two,
#' except 42, which stays 42
#' @param x input, must be numeric
#' @return magicified output
#' @export
do_magic <- function(x)
{
if (!is.numeric(x)) {
stop("x must be numeric");
}
out = x * 2;
out = replace(out, out == 84, 42);
out;
}
قائمة 1. وظيفة "do_magic"
يتم تخزين الدالة do_magic في ملف في موقع تقليدي ، وهو r/do_magic.r . تم توثيقه باستخدام حزمة "Roxygen2". تتحقق الوظيفة من الإدخال الصحيح ، وتفشل بسرعة إذا لم تتمكن من معالجة هذه.
تحتوي الحزمة على بعض الاختبارات ، باستخدام "اختبار" ، كما هو موضح أدناه:
context("do_magic")
test_that("do_magic: use", {
expect_equal(do_magic(42), 42)
expect_equal(do_magic(1), 2)
})
قائمة 2. اختبارات do_magic
يتم تخزين هذا الاختبار في ملف في موقع تقليدي ، وهو اختبارات/اختبار/اختبار do_magic.r . الاختبارات جميعها تمر. لا توجد أخطاء عند فحص الحزمة للبناء في RSTUDIO أو باستخدام DevTools :: Check () . هذا يعني أنه يمكن إرسال الحزمة إلى Cran دون أي مشكلة (باستثناء إقناع أن الحزمة ذات صلة)!
يعني التكامل المستمر أن تأثير الكود الذي تم تغييره ، بعد تحميله على github ، يظهر تلقائيًا بعد فترة زمنية قصيرة. بمعنى آخر: إذا لم تعد الحزمة لا يمكن أن تبني بعد الآن عن طريق عيب مقدمة (على سبيل المثال ، اختبار فشل الآن) ، فسيتم ملاحظة ذلك مبكرًا. أو ، إذا كسرها شخص آخر ، فسوف يلاحظ الفريق مبكرًا. أيضًا ، عندما يقدم شخص ما طلب سحب ، يمكن للمرء معرفة ما إذا كان سيؤدي إلى كسر بناء الحزمة قبل قبولها.
هناك العديد من خدمات التكامل المستمر الأخرى التي تعمل أيضًا ، مثل Jenkins و CodeShip و Circleci و Wercker. لقد صادفت للتو تعلم Travis CI أولاً.
الشكل 2. شعار Travis CI
الخطوة الأولى من الإعداد لدينا هي تنشيط Travis CI.
Travis CI هي خدمة تكامل مستمرة (وبالتالي ، "CI" في الاسم) مجانية في استخدام برنامج الخيط ويعمل بشكل جيد مع Github.
دعنا أولاً ننشط Travis CI ، لأنه فقط عند تنشيطه ، سيبدأ تشغيله عند التحميل إلى GitHub.
للقيام بذلك: انتقل إلى موقع Travis CI ، www.travis-ci.org ، وقم بتسجيل الدخول باستخدام حساب github. يطلب Travis إذنًا لبعض معلومات GitHub ، مثل اسم المستخدم والبريد الإلكتروني. بعد التفويض ، يعرض Travis CI جميع مستودعات GitHub الخاصة بالمستخدم وحالة التنشيط الخاصة بهم:
الشكل 3. نظرة عامة على githubs التي تم فحصها بواسطة Travis CI
في هذا الشكل ، يتم عرض المستخدم الذي يحتوي على ثلاثة مستودعات على الأقل من GitHub ، منها لا يتم تنشيطها (الصليب الرمادي) واثنان (الفحص الأخضر).
اذهب ابحث عن github لحزمة r وقم بتنشيطها.
تغطية الكود هي النسبة المئوية لخطوط التعليمات البرمجية التي تغطيها الاختبارات. إذا لم يتم اختبار الخط ، فلا يتم اكتشاف رمز ميت (يمكن إزالته) أو يجب أن يكون اختبارًا يستخدم هذا الرمز. ترتبط تغطية الكود بجودة الكود [Del Frate et al. ، 1995].
هناك خدمات أخرى تتبع تغطية الرمز ، مثل Code Climate و Codacity و Coveralls و QuantivionCode وغيرها الكثير. يحدث فقط أن الحزمة التي سنستخدمها ('Lintr') تستخدم codecov.
الشكل 4. شعار Codecov
الخطوة الثانية هي تفعيل Codecov.
Codecov هو موقع ويب يعرض تغطية رمز مستودع GitHub في نموذج سهل الاستخدام. يتتبع Codecov تغطية رمز المشروع طوال الوقت. إذا كان هناك العديد من فروع GIT ، يتم عرض تغطية الكود بشكل منفصل لكل فرع.
نحن بحاجة إلى تفعيل Codecov الآن ، لأن
سيتلقى Codecov فقط وتغطية رمز العرض للمستخدمين المسجلين.
لتفعيل Codecov ، انتقل إلى موقعه على الويب ، https://codecov.io ، وتسجيل الدخول مع حساب github. سيطلب تفويضًا لبعض معلومات github ، مثل اسم المستخدم والبريد الإلكتروني.
بعد التفويض ، يعرض Codecov تغطية الكود لجميع githubs للمستخدم. بالنسبة للمستخدم الجديد ، ستكون هذه الشاشة فارغة في الغالب ، حيث لم يتم قياس تغطية رمز حتى الآن. بالنسبة للمستخدم الذي يحتوي على تغطية رمز مستودعات Github متعددة ، ستبدو شاشة Codecov مثل هذا:
الشكل 5: مثال نظرة عامة على githubs التي تم فحصها بواسطة Codecov
في هذا الشكل ، يمكن للمرء أن يرى استخدامات تحتوي على ثلاثة مستودعات على الأقل من GitHub التي تم فحص تغطية الكود الخاصة بهم.
والخطوة الثالثة هي توجيه ترافيس CI بما يجب فعله عندما يتم تحميل رمز جديد على github المنشط.
يتم توجيه Travis إلى ما يجب القيام به باستخدام برنامج نصي بناء ، وهو ملف نص عادي يسمى .travis.yml . يبدأ اسم الملف بنقطة ، مما يجعله ملفًا مخفيًا على أنظمة UNIX. امتداد ".Yml" هو اختصار لـ "لغة أخرى ترميز". يتم توجيه Travis CI في لغة أمر باش.
في المجلد الجذر للمشروع ، قم بإنشاء ملف يسمى .travis.yml ، ووضع النص التالي فيه:
language: r
cache: packages
r_github_packages:
- jimhester/lintr
- jimhester/covr
- MangoTheCat/goodpractice
after_success:
- Rscript -e "lintr::lint_package()"
- Rscript -e "covr::codecov()"
- Rscript -e "goodpractice::gp()"
قائمة 3. نص Travis CI
هذا هو نصي بسيط ومباشر . travis.yml . ينص السطر الأول على أن لغة البرمجة المستخدمة هنا هي R. يخبر السطر الثاني Travis CI للحفاظ على الحزم المثبتة في ذاكرة التخزين المؤقت ، من أجل منع إعادة تثبيت هذه الحزم. يقوم قسم "R_Github_Packages" بتوجيه Travis CI لتثبيت هذه الحزم التي تستضيفها جيثب. يتم تشغيل قسم "After_success" بعد مرور الحزمة على DevTools :: Check () . في هذا القسم ، سيتم تشغيل الشيكات من حزم "Lintr" و "Covr" و "GoodPractice". المزيد على تلك الحزم لاحقًا.
بعد إنشاء ملف .travis.yml ، قم بتحميله على github.
بعد التحميل .travis.yml إلى github ، سيكون مرئيًا على github:
الشكل 6.
هذا الدفع إلى github يؤدي إلى Travis CI وسيبدأ على الفور في القيام بعمله.
يحتاج Travis CI إلى بعض الوقت لإعداد جهاز افتراضي. في كل مرة يتم فيها التحميل إلى github ، يتم إنشاء جهاز افتراضي ، لضمان بيئة بناء واختبار قابلة للتكرار.
لمشاهدة Travis CI تقوم بعملها ، عد إلى موقع Travis CI ، https://travis-ci.org . بعد دقيقة واحدة تقريبًا ، يصبح تقدم Travis CI مرئيًا. يقوم Travis CI أولاً بتثبيت جميع الحزم وتبعياتها. .
إليكم رأس حزمة "Prde" الأولى:
الشكل 7. رأس حزمة "prde" أول بناء لها
نعلم بالفعل أن الحزمة ستجتاز هذا الشيك ، حيث تم فحص ذلك بالفعل في RSTUDIO. في حالة عدم مرور البناء ، سيتم عرض الناتج نفسه على النحو الوارد في DevTools :: Check () ولا شيء أكثر من ذلك. إذا تم تمرير البناء ، فستكون هناك بعض المعلومات الجديدة في الأسفل:
الشكل 8. أسفل حزمة "prde" أول بناء لها
يكشف النقر فوق المثلثات على اليسار عن بعض المعلومات الإضافية.
أولاً ، سنوسع ردود الفعل من حزمة "Lintr" (بواسطة Jim Hester). يظهر:
الشكل 9. التعليقات التي قدمتها حزمة "Lintr"
"Lintr" عبارة عن حزمة للتحقق مما إذا كانت الحزمة أسلوب الترميز الخاص بها تتبع معايير جيدة التكوين ، مثل تلك الخاصة بـ Wickham (2014) و Wickham (2015).
الشكل 10. جيم هيستر
لا يظهر إخراج "Lintr" فقط على موقع Travis CI. كما سيعلق صديقي العزيز Lintr-Bot على الالتزام على Github ، مع نفس الرسائل بالضبط:
الشكل 11. تعليقات Lintr-Bot على الالتزام ، كما هو موضح في Github
Lintr-bot هو دائما على حق. إذا لزم الأمر ، يمكن صنع "Lintr" للسماح بمعايير الترميز الأخرى.
الشكل 12. شعار مانجوثيكات
بالانتقال من كلمات الحكمة المحطمة ، سنوسع ردود الفعل من حزمة "GoodPractice" (بواسطة Mangothecat). هذا واحد يظهر:
الشكل 13. ردود الفعل التي قدمتها حزمة "GoodPractice"
يمتد "GoodPractice" "Lintr" عن طريق إضافة ممارسات جيدة. على سبيل المثال ، قد يوحي بعدم استخدام وظيفة معينة ولكن استخدام بديل أفضل بدلاً من ذلك.
يوجد مثلث ثالث يمكن تمديده ، ويوفر معلومات حول المكالمة إلى حزمة "CoVR" ، في سجل إنشاء Travis. عرض هذه المعلومات هنا ليس مفيدًا ، حيث يتم عرضه في شكل خام. بدلاً من ذلك ، عد إلى موقع Codecov ، https://codecov.io ، لعرض تغطية الكود بطريقة أجمل:
الشكل 14. ردود الفعل التي قدمتها حزمة "COVR" ، كما هو معروضة بواسطة Codecov
تُظهر تغطية التعليمات البرمجية ، أن مؤلف حزمة "PRDE" قد نسي اختبار ما إذا كانت وظيفة do_magic تطرح بالفعل استثناء عندما لا يكون الإدخال عدديًا.
بفضل هذه الأدوات (والأشخاص الذين كتبوا هذه) ، من الأسهل أن تصبح مبرمج R أفضل.
أقترح الاستماع إلى هذه النصائح ومتابعة هذه.
إذا لم يوافق المرء على نصيحة الخبراء ، فأنا دائمًا فضولي لمعرفة السبب. اختار الخبراء هذه المعايير لسبب ما. ويدرك هؤلاء الخبراء أيضًا الحجج التي تفضل المعايير الأخرى.
بالنسبة لطلابي ، أقوم بفرض سجل نظيف "Oclint" و "GoodPractice" وتغطية رمز لا يقل عن 95 ٪.
يمكن استخدام هذه التقنيات من قبل الجميع من البداية إلى المبرمجين ذوي الخبرة. لتطوير الخيط ، فإن GitHub و Travis CI و Codecov مجانيون ، في حين أن تطوير المصدر المغلقة يطلب رسومًا.
Code better. Sleep better. [Langr, 2013]
عند إزالة جميع الاختبارات وتغطية الكود العالي ، قد يتم عرض ذلك للعالم. يمكن القيام بذلك عن طريق إضافة شارات بناء إلى ملف readme.md ، في المجلد الرئيسي لـ GitHub. مثل هذه الشارات تبدو هكذا:
الشكل 15. الشارات المعروضة على github 'prde'
لعرض هذه الشارات ، أضف الكود التالي إلى readme.md في المجلد الرئيسي لـ Github:
[](https://travis-ci.org/[yourname]/[package name])
[](https://codecov.io/github/[yourname]/[package name]?branch=master)
قائمة 4. عرض شارات الحالة
آمل أن يلهم الآخرين أن يفعلوا الشيء نفسه. فعلت ذلك من أجلي.
في هذه المقالة ، تعلمت كيفية السماح لنفسك بالتصحيح عند الانحراف عن الممارسة الجيدة للخبراء.
لقد أنشأنا وتنشيط حسابين لموقع الويب ومكتب ملف نصي واحد. سيتم ربح الوقت الذي استغرقنا من إعداد هذه الأدوات من التغييرات المستقبلية إلى حزمة R الخاصة بنا.
أود أن أشكر Luis Boullosa و Rampal S. Etienne و Cyrus A. Mallon على ملاحظاتهم على المسودات السابقة من هذه المقالة.
git push : أمر GIT لتحميل رمز معدّل إلى مضيف مستودع GIT
