Ruby Academy · Lezione

Scrivere il codice

Organizzare una gem

Scrivere il codice è una lezione Ruby Academy gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Ruby Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Ruby Academy include 4 lezioni in totale.

Organizzare il codice di un gem

Il buon codice di un gem è facile da leggere, da caricare con require ed è organizzato in namespace, così non entra mai in conflitto con altre librerie. Lo strumento chiave è un modulo di primo livello che racchiude tutto.

Un modulo namespace per ogni gem.
Un file per ogni classe, in corrispondenza con il namespace.
Una superficie pubblica ridotta.

Il modulo namespace

Racchiuda tutte le classi in un modulo denominato come il gem. In questo modo il suo Client non entrerà in conflitto con il Client di qualcun altro.

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

puts Greeter::Hello.new.message

Convenzione per i nomi dei file

Gli strumenti Ruby si aspettano che i percorsi dei file corrispondano ai nomi delle costanti:

Greeter si trova in lib/greeter.rb.
Greeter::Hello si trova in lib/greeter/hello.rb.

Questa convenzione consente ai caricatori automatici di trovare i file automaticamente.

Richiedere i file interni

Il file di ingresso collega tutto con require_relative. Ogni file di classe viene richiesto una sola volta, così l'intera libreria viene caricata con un singolo require 'greeter'.

Un'API pubblica chiara

Esponga un insieme ridotto di metodi che gli utenti chiamano effettivamente. Un modello comune consiste in metodi di comodo a livello del modulo che delegano alle classi interne.

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

puts Greeter.say("Ada")

Nascondere i dettagli interni

Contrassegni i metodi di supporto come private, così non fanno parte del contratto pubblico. Tutto ciò che è pubblico rappresenta una promessa agli utenti: mantenga questa superficie intenzionale e ridotta.

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)

Modello di configurazione

Molti gem offrono un blocco configure, così gli utenti possono impostare le opzioni una sola volta. Una versione semplice memorizza le impostazioni in un oggetto di configurazione.

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

Errori personalizzati

Definisca classi di errore specifiche del gem all'interno del namespace, così gli utenti possono intercettare esattamente i suoi errori. Le faccia ereditare da 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

Evitare il monkey patching

Eviti di modificare globalmente classi fondamentali come String. Questo provoca comportamenti inattesi nel resto del codice. Se deve estendere una classe, utilizzi refinements per circoscrivere la modifica oppure aggiunga metodi di supporto nelle proprie classi.

Ridurre le dipendenze

Ogni dipendenza a runtime che aggiunge diventa una dipendenza per tutti i suoi utenti. Quando è ragionevole, preferisca la libreria standard e aggiunga un gem solo quando il suo beneficio ne giustifica il peso.

Meno dipendenze significano meno conflitti tra versioni e installazioni più rapide.

Documentare l'API pubblica

Aggiunga commenti che descrivano gli argomenti e il valore restituito da ogni metodo pubblico. Strumenti come YARD trasformano questi commenti in documentazione consultabile, e un buon README con esempi spesso determina l'adozione del gem.

Verifica rapida

Verifichi la comprensione dell'organizzazione del codice di un gem.

Riepilogo: scrivere il codice

Ha appreso come organizzare i dettagli interni di un gem:

Racchiudere tutto in un modulo namespace.
Far corrispondere i percorsi dei file ai nomi delle costanti.
Mantenere un'API pubblica ridotta e contrassegnare i metodi di supporto come private.
Definire classi di errore personalizzate ed evitare il monkey patching globale.
Mantenere leggere le dipendenze e documentare l'API.

Ora aggiungerà test e versionamento.

Domande Frequenti

La lezione «Scrivere il codice» è gratuita?

Sì — il testo completo di «Scrivere il codice» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Ruby Academy, passa a CoddyKit PRO. Il corso Ruby Academy include 4 lezioni in totale.

Cosa imparerò in «Scrivere il codice»?

Organizzare una gem Eserciti Ruby Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare Ruby Academy?

Non è richiesta alcuna esperienza precedente. Ruby Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.

Quanto tempo richiede la lezione «Scrivere il codice»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione Ruby Academy?

Sì. Ogni lezione Ruby Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a Ruby Academy