Ruby Academy · Lekcja

Pisanie kodu

Organizowanie gema

Pisanie kodu to bezpłatna lekcja Ruby Academy na CoddyKit. To lekcja 2 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Ruby Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Ruby Academy zawiera 4 lekcji w sumie.

Organizowanie kodu gema

Dobry kod gema jest łatwy do odczytania i wczytania oraz korzysta z przestrzeni nazw, dzięki czemu nigdy nie koliduje z innymi bibliotekami. Najważniejszym narzędziem jest moduł najwyższego poziomu, który obejmuje całość.

Jedna przestrzeń nazw na gem.
Jeden plik na klasę, odzwierciedlający przestrzeń nazw.
Niewielki publiczny interfejs.

Moduł przestrzeni nazw

Należy umieścić wszystkie klasy w module nazwanym tak jak gem. Zapobiega to kolizji klasy Client z klasą Client należącą do innej biblioteki.

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

puts Greeter::Hello.new.message

Konwencja nazewnictwa plików

Narzędzia Ruby oczekują, że ścieżki plików będą odpowiadać nazwom stałych:

Greeter znajduje się w lib/greeter.rb.
Greeter::Hello znajduje się w lib/greeter/hello.rb.

Ta konwencja pozwala autoloaderom automatycznie odnajdywać pliki.

Dołączanie plików wewnętrznych

Plik wejściowy spina wszystko za pomocą require_relative. Każdy plik klasy jest dołączany raz, dzięki czemu cała biblioteka ładuje się za pomocą pojedynczego require 'greeter'.

Przejrzyste publiczne API

Należy udostępniać niewielki zestaw metod, z których użytkownicy faktycznie korzystają. Częstym wzorcem są wygodne metody na poziomie modułu, które delegują działanie do klas wewnętrznych.

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

puts Greeter.say("Ada")

Ukrywanie szczegółów wewnętrznych

Należy oznaczać metody pomocnicze jako private, aby nie były częścią publicznego kontraktu. Wszystko, co jest publiczne, stanowi obietnicę złożoną użytkownikom, dlatego publiczny interfejs powinien być przemyślany i niewielki.

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)

Wzorzec konfiguracji

Wiele gemów udostępnia blok configure, w którym użytkownicy mogą jednorazowo ustawić opcje. Prosta wersja przechowuje ustawienia w obiekcie konfiguracji.

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

Własne błędy

Należy zdefiniować klasy błędów właściwe dla gema w jego przestrzeni nazw, aby użytkownicy mogli przechwytywać dokładnie te błędy. Klasy te powinny dziedziczyć po 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

Unikanie monkey patchingu

Należy unikać globalnego modyfikowania podstawowych klas, takich jak String. Powoduje to nieoczekiwane skutki w innym kodzie. Jeśli rozszerzenie jest konieczne, należy użyć refinements, aby ograniczyć zmianę do określonego zakresu, albo dodać metody pomocnicze we własnych klasach.

Ograniczanie zależności

Każda dodana zależność środowiska wykonawczego staje się zależnością wszystkich użytkowników gema. Gdy jest to uzasadnione, należy preferować bibliotekę standardową i dodawać gem tylko wtedy, gdy jest wart dodatkowego obciążenia.

Mniejsza liczba zależności oznacza mniej konfliktów wersji i szybsze instalacje.

Dokumentowanie publicznego API

Należy dodawać komentarze opisujące argumenty i wartość zwracaną każdej publicznej metody. Narzędzia takie jak YARD przekształcają je w przeglądalną dokumentację, a dobre README z przykładami często decyduje o tym, czy użytkownicy wybiorą dany gem.

Szybkie sprawdzenie

Proszę sprawdzić swoją wiedzę o organizowaniu kodu gema.

Podsumowanie: pisanie kodu

W tej części poznano sposób organizowania elementów wewnętrznych gema:

Całość należy umieścić w module przestrzeni nazw.
Ścieżki plików powinny odpowiadać nazwom stałych.
Należy utrzymywać niewielkie publiczne API i oznaczać metody pomocnicze jako private.
Należy definiować własne klasy błędów i unikać globalnego monkey patchingu.
Należy ograniczać zależności i dokumentować API.

W następnej części dodamy testy i wersjonowanie.

Często zadawane pytania

Czy lekcja „Pisanie kodu” jest bezpłatna?

Tak — pełny tekst „Pisanie kodu” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Ruby Academy, przejdź na CoddyKit PRO. Kurs Ruby Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Pisanie kodu”?

Organizowanie gema Ćwiczysz Ruby Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Ruby Academy?

Nie wymagamy żadnego doświadczenia. Ruby Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 2 z 4.

Ile czasu zajmuje lekcja „Pisanie kodu”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Ruby Academy?

Tak. Każda lekcja Ruby Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do Ruby Academy