Ruby Academy · Lesson

Writing the Code

Organizing a gem.

Writing the Code is a free Ruby Academy lesson on CoddyKit — lesson 2 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Ruby Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

Organizing a Gem's Code

Good gem code is easy to read, easy to require, and namespaced so it never collides with other libraries. The key tool is a top-level module that wraps everything.

One namespace module per gem.
One file per class, mirroring the namespace.
A small public surface.

The Namespace Module

Wrap all classes in a module named after your gem. This prevents your Client from clashing with someone else's Client.

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

puts Greeter::Hello.new.message

File Naming Convention

Ruby tooling expects file paths to match constant names:

Greeter lives in lib/greeter.rb.
Greeter::Hello lives in lib/greeter/hello.rb.

This convention lets autoloaders find files automatically.

Requiring Internal Files

The entry file ties everything together with require_relative. Each class file is required once so the whole library loads with a single require 'greeter'.

A Clear Public API

Expose a small set of methods users actually call. A common pattern is module-level convenience methods that delegate to internal classes.

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

puts Greeter.say("Ada")

Hiding Internals

Mark helper methods private so they are not part of your public contract. Anything public is a promise to users; keep that surface intentional and small.

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)

Configuration Pattern

Many gems offer a configure block so users can set options once. A simple version stores settings on a configuration object.

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

Custom Errors

Define gem-specific error classes under your namespace so users can rescue exactly your errors. Inherit from 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

Avoid Monkey Patching

Resist editing core classes like String globally. It causes surprises in other code. If you must extend, use refinements so the change is scoped, or add helper methods in your own classes.

Keep Dependencies Light

Every runtime dependency you add becomes a dependency for all your users. Prefer the standard library when reasonable, and only add a gem when it earns its weight.

Fewer dependencies mean fewer version conflicts and faster installs.

Document the Public API

Add comments describing each public method's arguments and return value. Tools like YARD turn these into browsable docs, and a good README with examples is often what decides whether people adopt your gem.

Quick Check

Test your understanding of organizing gem code.

Recap: Writing the Code

You learned how to organize gem internals:

Wrap everything in a namespace module.
Match file paths to constant names.
Keep a small public API and mark helpers private.
Define custom error classes and avoid global monkey patching.
Keep dependencies light and document the API.

Next we add tests and versioning.

Frequently asked questions

Is the “Writing the Code” lesson free?

Yes — the full text of “Writing the Code” is free to read here on the web, and the Ruby Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Ruby Academy course, upgrade to CoddyKit PRO.

What will I learn in “Writing the Code”?

Organizing a gem. You practise Ruby Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Ruby Academy?

No prior experience is required. Ruby Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 2 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Writing the Code” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Ruby Academy lesson?

Yes. Every Ruby Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Ruby Academy