Ruby Academy · Урок

Написание кода

Организуйте gem

«Написание кода» — бесплатный урок Ruby Academy на CoddyKit. Это урок 2 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Ruby Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Ruby Academy содержит 4 уроков всего.

Организация кода гема

Хороший код гема легко читать и подключать, а благодаря пространству имён он никогда не конфликтует с другими библиотеками. Главный инструмент здесь — модуль верхнего уровня, который оборачивает весь код.

Один модуль пространства имён на гем.
Отдельный файл для каждого класса, соответствующий пространству имён.
Небольшой публичный интерфейс.

Модуль пространства имён

Оберните все классы в модуль, названный по имени гема. Это не даст Вашему 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'.

Понятный публичный API

Предоставляйте небольшой набор методов, которые действительно вызывают пользователи. Распространённый шаблон — удобные методы на уровне модуля, делегирующие работу внутренним классам.

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)

Шаблон конфигурации

Многие гемы предоставляют блок настройки, чтобы пользователи могли один раз задать параметры. В простом варианте настройки хранятся в объекте конфигурации.

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

Пользовательские ошибки

Определяйте специфичные для гема классы ошибок в своём пространстве имён, чтобы пользователи могли перехватывать именно Ваши ошибки. Наследуйте от 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

Избегайте глобального переопределения классов

Не изменяйте глобально базовые классы, такие как String. Это приводит к неожиданностям в другом коде. Если расширение необходимо, используйте рефинменты, чтобы ограничить область действия изменения, или добавляйте вспомогательные методы в собственные классы.

Не перегружайте зависимости

Каждая добавленная зависимость во время выполнения становится зависимостью для всех пользователей. Если это разумно, предпочитайте стандартную библиотеку и добавляйте гем только тогда, когда он оправдывает свою стоимость.

Меньшее число зависимостей означает меньше конфликтов версий и более быструю установку.

Документируйте публичный API

Добавляйте комментарии с описанием аргументов и возвращаемого значения каждого публичного метода. Инструменты вроде YARD превращают их в удобную для просмотра документацию, а хороший README с примерами часто определяет, выберут ли пользователи Ваш гем.

Быстрая проверка

Проверьте своё понимание организации кода гема.

Итоги: написание кода

Вы узнали, как организовать внутреннюю часть гема:

Обернуть весь код в модуль пространства имён.
Сопоставлять пути файлов с именами констант.
Поддерживать небольшой публичный API и помечать вспомогательные методы как private.
Определять собственные классы ошибок и избегать глобального переопределения классов.
Не перегружать зависимости и документировать API.

Далее мы добавим тесты и управление версиями.

Часто задаваемые вопросы

Урок «Написание кода» бесплатный?

Да — полный текст урока «Написание кода» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 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 включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к Ruby Academy