Ruby Academy · درس

كتابة الشيفرة

تنظيم Gem

كتابة الشيفرة درس مجاني في Ruby Academy على CoddyKit. هذا هو الدرس 2 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Ruby Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Ruby Academy 4 دروس في المجموع.

تنظيم شيفرة Gem

تكون شيفرة gem الجيدة سهلة القراءة، وسهلة التحميل باستخدام require، ومنظمة ضمن مساحة أسماء حتى لا تتعارض مطلقًا مع المكتبات الأخرى. والأداة الأساسية لذلك هي وحدة ذات مستوى أعلى تغلّف كل شيء.

وحدة مساحة أسماء واحدة لكل gem.
ملف واحد لكل فئة، بما يعكس مساحة الأسماء.
واجهة عامة صغيرة.

وحدة مساحة الأسماء

غلّف جميع الفئات في وحدة تحمل اسم gem الخاص بك. يمنع ذلك Client الخاص بك من التعارض مع Client الخاص بشخص آخر.

module Greeter
  class Hello
    def message
      "Hi there"
    end
  end
end

puts Greeter::Hello.new.message

اصطلاح تسمية الملفات

تتوقع أدوات Ruby أن تتطابق مسارات الملفات مع أسماء الثوابت:

توجد Greeter في lib/greeter.rb.
توجد Greeter::Hello في lib/greeter/hello.rb.

يتيح هذا الاصطلاح لمحملات الأصناف العثور على الملفات تلقائيًا.

طلب الملفات الداخلية

يربط ملف الدخول كل شيء باستخدام require_relative. ويُطلب كل ملف فئة مرة واحدة، بحيث تُحمّل المكتبة بأكملها باستخدام require 'greeter' واحد.

واجهة برمجة تطبيقات عامة واضحة

اعرض مجموعة صغيرة من الدوال التي يستدعيها المستخدمون فعليًا. ومن الأنماط الشائعة توفير دوال مساعدة على مستوى الوحدة تفوّض العمل إلى الفئات الداخلية.

module Greeter
  def self.say(name)
    "Hello, " + name + "!"
  end
end

puts Greeter.say("Ada")

إخفاء التفاصيل الداخلية

ضع الدوال المساعدة تحت private حتى لا تصبح جزءًا من عقدك العام. كل ما هو عام يُعد وعدًا للمستخدمين؛ لذا اجعل هذه الواجهة مقصودة وصغيرة.

class Calculator
  def total(a, b)
    add(a, b)
  end

  private

  def add(x, y)
    x + y
  end
end

puts Calculator.new.total(2, 3)

نمط الإعداد

توفر العديد من gems كتلة configure حتى يتمكن المستخدمون من ضبط الخيارات مرة واحدة. وتخزّن نسخة بسيطة منها الإعدادات في كائن إعدادات.

module App
  class Config
    attr_accessor :api_key
  end

  def self.config
    @config ||= Config.new
  end

  def self.configure
    yield(config)
  end
end

App.configure { |c| c.api_key = "secret" }
puts App.config.api_key

أخطاء مخصصة

عرّف فئات أخطاء خاصة بـ gem ضمن مساحة الأسماء الخاصة بك، حتى يتمكن المستخدمون من معالجة أخطائك تحديدًا باستخدام rescue. اجعلها ترث من StandardError.

module Payment
  class Error < StandardError; end
  class DeclinedError < Error; end
end

begin
  raise Payment::DeclinedError, "card declined"
rescue Payment::Error => e
  puts "Handled: " + e.message
end

تجنب تعديل الأصناف بطريقة Monkey Patching

تجنب تعديل الأصناف الأساسية مثل String على مستوى النظام. فهذا يسبب مفاجآت في الشيفرات الأخرى. وإذا كان لا بد من التوسعة، فاستخدم refinements بحيث يكون التغيير محدود النطاق، أو أضف دوالًا مساعدة إلى أصنافك الخاصة.

أبقِ التبعيات قليلة

كل تبعية لوقت التشغيل تضيفها تصبح تبعية لجميع مستخدميك. فضّل المكتبة القياسية عندما يكون ذلك مناسبًا، ولا تضف gem إلا إذا كانت فائدته تبرر تكلفته.

تعني التبعيات الأقل تعارضات أقل بين الإصدارات وتثبيتًا أسرع.

وثّق واجهة برمجة التطبيقات العامة

أضف تعليقات تصف وسائط كل دالة عامة وقيمتها المرجعة. وتحول أدوات مثل YARD هذه التعليقات إلى وثائق قابلة للتصفح، وغالبًا ما يكون README جيد مرفق بأمثلة هو العامل الحاسم في تبني الآخرين لـ gem الخاص بك.

تحقق سريع

اختبر مدى فهمك لتنظيم شيفرة gem.

مراجعة: كتابة الشيفرة

لقد تعلمت كيفية تنظيم الأجزاء الداخلية لـ gem:

غلّف كل شيء في وحدة مساحة أسماء.
طابق مسارات الملفات مع أسماء الثوابت.
حافظ على واجهة برمجة تطبيقات عامة صغيرة، وضع الدوال المساعدة تحت private.
عرّف فئات أخطاء مخصصة وتجنب تعديل الأصناف الأساسية على مستوى النظام.
أبقِ التبعيات قليلة ووثّق واجهة برمجة التطبيقات.

سنضيف بعد ذلك الاختبارات وإدارة الإصدارات.

الأسئلة الشائعة

هل درس «كتابة الشيفرة» مجاني؟

نعم — نص درس «كتابة الشيفرة» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Ruby Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Ruby Academy 4 دروس في المجموع.

ماذا ستتعلم في «كتابة الشيفرة»؟

تنظيم Gem تتمرن على Ruby Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Ruby Academy؟

لا تُشترط خبرة سابقة. Ruby Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 2 من أصل 4.

كم من الوقت يستغرق درس «كتابة الشيفرة»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Ruby Academy هذا؟

نعم. كل درس في Ruby Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Ruby Academy