Skip to content

Latest commit

 

History

History
1603 lines (1261 loc) · 44.2 KB

README-frFR.md

File metadata and controls

1603 lines (1261 loc) · 44.2 KB

Préambule

Le style est ce qui sépare le bon de l'excellent.
-- Bozhidar Batsov

Une chose m'a toujours gêné en tant que développeur Ruby - les développeurs Python ont une super référence de style de programmation (PEP-8) alors que nous n'avons jamais eu un tel guide officiel, définissant le style et les bonnes pratiques de programmation Ruby. Et je pense que le style compte. Je pense également que des gens biens, tels que nous, développeurs Ruby, devraient être tout à fait capables de produire ce document convoité.

Ce guide (écrit par votre serviteur) a vu le jour en tant que convention de programmation Ruby interne à notre entreprise. Au bout d'un certain temps, il m'a semblé que ce travail pourrait s'avérer intéressant pour les membres de la communauté ruby en général et que le monde n'avait pas vraiment besoin d'une convention de programmation interne de plus. Mais le monde pourrait certainement tirer profit d'un ensemble de pratiques, d'idiomes et de conseils de style pour la programmation Ruby.

Dès le lancement de ce guide, j'ai reçu énormément de retours des membres de l'exceptionnelle communauté Ruby à travers le monde. Merci pour toutes les suggestions et votre soutien! Ensemble, nous pouvons créer une ressource bénéfique à tous les développeurs Ruby ici présents.

Au fait, si vous faites du Rails, vous pouvez consulter le Guide de style Ruby on Rails 3 complémentaire.

Le guide de style Ruby

Ce guide de style Ruby recommande des bonnes pratiques conçues pour qu'un programmeur Ruby du monde réel puisse produire un code qui puisse être maintenu par d'autres programmeurs Ruby du monde réel. Un guide de style qui reflète les utilisations du monde réel est utilisé, et un guide de style qui repose sur un idéal qui a été rejeté par les personnes qu'il est censé aider a de bonnes chances de ne pas être utilisé du tout – peu importe sa qualité.

Le guide est divisé en plusieurs sections de règles connexes. J'ai essayé d'ajouter le rationnel derrière les règles (j'ai omis certains points que je considérais plutôt évidents).

Ces règles ne sont pas sorties de nulle part - la majeure partie est basée sur ma longue carrière d'ingénieur logiciel, les retours et les suggestions des membres de la communauté Ruby et diverses ressources très renommées sur la programmation Ruby, telles que "Programming Ruby 1.9" et "The Ruby Programming Language".

Ce guide est toujours un travail en cours - certaines règles n'ont pas d'exemple, d'autres ont des exemples qui ne les illustre pas assez clairement. Ces problèmes seront corrigés tôt ou tard - gardez les juste à l'esprit pour l'instant.

Vous pouvez générer une copie PDF ou HTML de ce guide en utilisant Transmuter.

Le projet rubocop vise à fournir un moyen automatisé pour vérifier si un code Ruby est conforme avec le guide de style. Pour l'instant, il est loin d'être prêt pour la production et il lui manque beaucoup de fonctionnalités. Naturellement, tout le monde est invité à participer à son amélioration!

Des traductions de ce guide sont disponibles dans les langues suivantes :

Table des matières

Structure du code source

Chacun de nous ou presque est convaincu que tous les styles sauf le notre sont moches et illisibles. Retirez "sauf le notre" et nous aurons probablement raison...
-- Jerry Coffin (à propos de l'indentation)

  • Utilisez l'UTF-8 comme encodage des fichiers source.

  • Utilisez deux espaces par niveau d'indentation. Pas de tabulation.

    # bien
    def some_method
      do_something
    end
    
    # mauvais - quatre espaces
    def some_method
        do_something
    end
  • Utilisez des fins de ligne de type Unix. (*Les utilisateurs BSD/Solaris/Linux/OSX sont couverts par défaut, les utilisateurs Windows doivent faire très attention.)

    • Si vous utilisez Git, vous pouvez ajouter les paramètres de configuration suivants pour protéger votre projet des fins de ligne Windows qui traîneraient:

      $ git config --global core.autocrlf true

  • Utilisez des espaces autour des opérateurs, après les deux points, points-virgules et virgules, autour de { et devant }. L'espace est (généralement) sans importance pour l'interpréteur Ruby, mais l'utiliser correctement permet d'écrire facilement du code lisible.

    sum = 1 + 2
    a, b = 1, 2
    1 > 2 ? true : false; puts 'Hi'
    [1, 2, 3].each { |e| puts e }

    L'opérateur d'exposant est la seule exception:

    # mauvais
    e = M * c ** 2
    
    # bien
    e = M * c**2
  • Pas d'espace après (, [ ou devant ], ).

    some(arg).other
    [1, 2, 3].length
  • Indenter when au même niveau que case. Je sais que beaucoup seront en désaccord avec cette règle, mais c'est un style établi dans "The Ruby Programming Language" et "Programming Ruby".

    case
    when song.name == 'Misty'
      puts 'Not again!'
    when song.duration > 120
      puts 'Too long!'
    when Time.now.hour > 21
      puts "It's too late"
    else
      song.play
    end
    
    kind = case year
           when 1850..1889 then 'Blues'
           when 1890..1909 then 'Ragtime'
           when 1910..1929 then 'New Orleans Jazz'
           when 1930..1939 then 'Swing'
           when 1940..1950 then 'Bebop'
           else 'Jazz'
           end
  • Passez des lignes entre les def pour diviser la méthode en paragraphes logiques.

    def some_method
      data = initialize(options)
    
      data.manipulate!
    
      data.result
    end
    
    def some_method
      result
    end
  • Alignez les paramètres de l'appel de méthode s'ils s'étalent sur plus d'une ligne.

    # point de départ (ligne trop longue)
    def send_mail(source)
      Mailer.deliver(to: '[email protected]', from: '[email protected]', subject: 'Important message', body: source.text)
    end
    
    # mauvais (indentation normale)
    def send_mail(source)
      Mailer.deliver(
        to: '[email protected]',
        from: '[email protected]',
        subject: 'Important message',
        body: source.text)
    end
    
    # mauvais (double indentation)
    def send_mail(source)
      Mailer.deliver(
          to: '[email protected]',
          from: '[email protected]',
          subject: 'Important message',
          body: source.text)
    end
    
    # bien
    def send_mail(source)
      Mailer.deliver(to: '[email protected]',
                     from: '[email protected]',
                     subject: 'Important message',
                     body: source.text)
    end
  • Ajoutez des tirets bas aux grands expressions numériques pour améliorer leur lisibilité.

    # mauvais - combien y a-t-il de zéros?
    num = 1000000
    
    # bien - bien plus simple à analyser pour le cerveau humain
    num = 1_000_000
  • Utilisez RDoc et ses conventions pour la documentation d'API. Ne passez pas de ligne entre le bloc de commentaire et le def.

  • Limitez les lignes à 80 caractères.

  • Evitez de laisser des espaces en fin de ligne.

Syntaxe

  • Utilisez def avec des parenthèses quand il y a des arguments. Omettez les parenthèses quand la méthode n'accepte pas d'argument.

    def some_method
      # body omitted
    end
    
    def some_method_with_arguments(arg1, arg2)
      # body omitted
    end
  • N'utilisez jamais for, sauf si vous savez exactement pourquoi. En général, il vaut mieux utiliser les itérateurs. for est implémenté à la suite de each, mais avec une différence - for n'a pas de contexte propre (contrairement à each) et les variables définies dans son bloc seront visibles en dehors.

    arr = [1, 2, 3]
    
    # mauvais
    for elem in arr do
      puts elem
    end
    
    # bien
    arr.each { |elem| puts elem }
  • N'utilisez jamais then pour les if/unless sur plusieurs lignes.

    # mauvais
    if some_condition then
      # body omitted
    end
    
    # bien
    if some_condition
      # body omitted
    end
  • Privilégiez l'opérateur ternaire (?:) plutôt que des structures if/then/else/end. C'est plus courant et visiblement plus compact.

    # mauvais
    result = if some_condition then something else something_else end
    
    # bien
    result = some_condition ? something : something_else
  • Utilisez une seule expression par section dans un opérateur ternaire. Autrement dit, les opérateurs ternaires ne doivent pas être imbriqués. Privilégiez les structures if/else le cas échéant.

    # mauvais
    some_condition ? (nested_condition ? nested_something : nested_something_else) : something_else
    
    # bien
    if some_condition
      nested_condition ? nested_something : nested_something_else
    else
      something_else
    end
  • N'utilisez jamais if x: ... - cette syntaxe est supprimée en Ruby 1.9. Utilisez l'opérateur ternaire à la place.

    # mauvais
    result = if some_condition: something else something_else end
    
    # bien
    result = some_condition ? something : something_else
  • N'utilisez jamais if x; .... Utilisez l'opérateur ternaire à la place.

  • Utilisez when x then ... pour les case sur une seule ligne. La syntaxe alternative when x: ... est supprimée en Ruby 1.9.

  • N'utilisez jamais when x; .... Voir règle précédente.

  • Utilisez &&/|| pour les expressions booléennes, and/or pour le flux de contrôle. (Règle d'or: Si vous devez mettre des parenthèses exterieures, vous utilisez les mauvais opérateurs.)

    # expression booléenne
    if some_condition && some_other_condition
      do_something
    end
    
    # flux de contrôle
    document.saved? or document.save!
  • Evitez les ?: sur plusieurs lignes (opérateur ternaire); utilisez if/unless à la place.

  • Privilégiez l'utilisation des modificateurs if/unless pour les structures sur simple ligne. L'utilisation du contrôle de flux and/or est une alternative acceptable.

    # mauvais
    if some_condition
      do_something
    end
    
    # bien
    do_something if some_condition
    
    # alternative acceptable
    some_condition and do_something
  • Privilégiez unless plutôt que if pour les conditions négatives (ou le contrôle de flux or).

    # mauvais
    do_something if !some_condition
    
    # bien
    do_something unless some_condition
    
    # alternative acceptable
    some_condition or do_something
  • N'utilisez jamais unless avec else. Réécrivez ces structures avec le cas positif en premier.

    # mauvais
    unless success?
      puts 'failure'
    else
      puts 'success'
    end
    
    # bien
    if success?
      puts 'success'
    else
      puts 'failure'
    end
  • N'utilisez pas de parenthèses autour d'une condition if/unless/while, sauf si la condition contient une affectation (voir "Utilisation de la valeur de retour de =" ci-dessous).

    # mauvais
    if (x > 10)
      # contenu omis
    end
    
    # bien
    if x > 10
      # contenu omis
    end
    
    # acceptable
    if (x = self.next_value)
      # contenu omis
    end
  • Privilégiez l'utilisation d'un modificateur while/until pour les structures à simple ligne.

    # mauvais
    while some_condition
      do_something
    end
    
    # bien
    do_something while some_condition
  • Privilégiez until plutôt que while pour les conditions négatives.

    # mauvais
    do_something while !some_condition
    
    # bien
    do_something until some_condition
  • Omettez les parenthèses pour les méthodes qui font partie d'un DSL (Domain Specific Langage - ex: Rake, Rails, RSpec), qui ont un statut de "mot clé" en Ruby (ex: attr_reader, puts) et les méthodes d'accès à des attributs. Utilisez les parenthèses autour des arguments de toutes les autres invocations de méthodes.

    class Person
      attr_reader :name, :age
    
      # omis
    end
    
    temperance = Person.new('Temperance', 30)
    temperance.name
    
    puts temperance.age
    
    x = Math.sin(y)
    array.delete(e)
  • Privilégiez {...} plutôt que do...end pour les blocs sur simple ligne. Evitez l'utilisation de {...} pour les blocs multi-lignes (les enchainements multi-lignes sont toujours moches). Utilisez toujours do...end pour le "flux de contrôle" et les "définitions de méthodes" (ex: dans les Rakefiles et certains DSLs). Evitez les do...end dans les enchainements.

    names = ['Bozhidar', 'Steve', 'Sarah']
    
    # bien
    names.each { |name| puts name }
    
    # mauvais
    names.each do |name|
      puts name
    end
    
    # bien
    names.select { |name| name.start_with?('S') }.map { |name| name.upcase }
    
    # mauvais
    names.select do |name|
      name.start_with?('S')
    end.map { |name| name.upcase }

    Certains prétendront que les enchainements multi-lignes ont une bonne apparence en utilisant {...}, mais ils devraient se demander - est-ce que ce code est vraiment lisible et est-ce que le contenu des blocs peut être extrait dans des méthodes efficaces?

  • Evitez return quand il n'est pas nécessaire pour le flux de contrôle.

    # mauvais
    def some_method(some_arr)
      return some_arr.size
    end
    
    # bien
    def some_method(some_arr)
      some_arr.size
    end
  • Evitez self quand il n'est pas nécessaire. (C'est nécessaire uniquement pour appeller un accesseur d'écriture local.)

    # mauvais
    def ready?
      if self.last_reviewed_at > self.last_updated_at
        self.worker.update(self.content, self.options)
        self.status = :in_progress
      end
      self.status == :verified
    end
    
    # bien
    def ready?
      if last_reviewed_at > last_updated_at
        worker.update(content, options)
        self.status = :in_progress
      end
      status == :verified
    end
  • En conséquence, évitez les ambiguïtés avec des variables locales, sauf si elles sont équivalentes.

    class Foo
      attr_accessor :options
    
      # acceptable
      def initialize(options)
        self.options = options
        # options et self.options sont ici équivalentes
      end
    
      # mauvais
      def do_something(options = {})
        unless options[:when] == :later
          output(self.options[:message])
        end
      end
    
      # bien
      def do_something(params = {})
        unless params[:when] == :later
          output(options[:message])
        end
      end
    end
  • Utilisez des espaces autour de l'opérateur = lors de l'assignation de valeurs par défaut à des paramètres de méthode:

    # mauvais
    def some_method(arg1=:default, arg2=nil, arg3=[])
      # do something...
    end
    
    # bien
    def some_method(arg1 = :default, arg2 = nil, arg3 = [])
      # do something...
    end

    Bien que beaucoup de livres Ruby conseillent le premier style, le second est bien plus fréquent (et probablement un peu plus lisible).

  • Evitez les prolongements de lignes (\) quand ils ne sont pas indispensables. En pratique, évitez les prolongements de ligne tout court.

    # mauvais
    result = 1 - \
             2
    
    # bien (mais toujours extrêmement moche)
    result = 1 \
             - 2
  • Utiliser la valeur de retour d'un = (une affectation) est acceptable, mais entourez l'assignement de parenthèses.

    # bien - montre l'utilisation prévue de l'affectation
    if (v = array.grep(/foo/)) ...
    
    # mauvais
    if v = array.grep(/foo/) ...
    
    # bien également - montre l'utilisation prévue de l'affectation et la priorité est correcte.
    if (v = self.next_value) == 'hello' ...
  • Utilisez ||= à vonlonté pour initialiser les variables.

    # définit Bozhidar comme nom, seulement s'il vaut nil ou false
    name ||= 'Bozhidar'
  • N'utilisez pas ||= pour initialiser des variables booléennes. (Imaginez ce qu'il se passerait si la valeur actuelle était false.)

    # mauvais - définirait enabled à true, même si elle valait false
    enabled ||= true
    
    # bien
    enabled = true if enabled.nil?
  • Evitez d'utiliser des variables spéciales de type Perl (comme $0-9, `$``, etc. ). Elles sont incompréhensibles et toute utilisation dans un script de plus d'une ligne est vivement déconseillée.

  • Ne mettez jamais d'espace entre le nom d'une méthode et la parenthèse d'ouverture.

    # mauvais
    f (3 + 2) + 1
    
    # bien
    f(3 + 2) + 1
  • Si le premier argument d'une méthode commence par une parenthèse ouvrante, utilisez toujours des parenthèses pour l'invocation de méthode. Ecrivez par exemple f((3 + 2) + 1).

  • Lancez toujours l'interpréteur ruby avec l'option -w pour qu'il vous avertisse si vous avez oublié l'une des règles ci-dessus!

  • La nouvelle notation hash est à privilégier en Ruby 1.9 quand les clés de hash sont des symboles.

    # mauvais
    hash = { :one => 1, :two => 2 }
    
    # bien
    hash = { one: 1, two: 2 }
  • La nouvelle syntaxe lambda est à privilégier en Ruby 1.9.

    # mauais
    lambda = lambda { |a, b| a + b }
    lambda.call(1, 2)
    
    # bien
    lambda = ->(a, b) { a + b }
    lambda.(1, 2)
  • Utilisez _ pour les paramètres de bloc inutilisés.

    # mauvais
    result = hash.map { |k, v| v + 1 }
    
    # bien
    result = hash.map { |_, v| v + 1 }

Nommage

Les seules vraies difficultés en programmation sont l'invalidation de cache et nommer les choses.
-- Phil Karlton

  • Utilisez le snake_case pour les méthodes et les variables.

  • Utilisez le CamelCase pour les classes et les modules. (Gardez les acronymes comme HTTP, RFC, XML en majuscules.)

  • Utilisez le SCREAMING_SNAKE_CASE pour les autres constantes.

  • Le nom des méthodes qui retournent obligatoirement une valeur booléenne doit finir par un point d'interrogation. (ex: Array#empty?).

  • Le nom des méthodes potentiellement "dangereuses" (ex: les méthodes qui modifient self ou les arguments, exit! (qui n'exécute pas les finaliseurs contrairement à exit), etc.) devraient finir par un point d'exclamation (bang) s'il existe une version sécurisée de cette méthode dangereuse.

    # mauvais - il n'y a pas de méthode 'sécurisée'
    class Person
      def update!
      end
    end
    
    # bien
    class Person
      def update
      end
    end
    
    # bien
    class Person
      def update!
      end
    
      def update
      end
    end
  • Définissez la méthode "non bang" (sécurisée) à la suite de la version "bang" (dangereuse) si possible.

    class Array
      def flatten_once!
        res = []
    
        each do |e|
          [*e].each { |f| res << f }
        end
    
        replace(res)
      end
    
      def flatten_once
        dup.flatten_once!
      end
    end
  • Lorsque vous utilisez reduce avec un bloc court, nommez les arguments |a, e| (accumulator, element).

  • Lorsque vous définissez des opérateurs binaires, nommez l'argument other.

    def +(other)
      # contenu omis
    end
  • Privilégiez map plutôt que collect, find plutôt que detect, select plutôt que find_all, reduce plutôt que inject et size plutôt que length. Ce n'est pas une exigence absolue; si l'utilisation de l'alias améliore la lisibilité, il est acceptable de l'utiliser. Les methodes qui riment sont un héritage de Smalltalk et ne sont pas courantes dans les autres langages de programmation. La raison pour laquelle l'utilisation de select est encouragée plutôt que find_all est qu'elle fonctionne bien avec reject et que son nom est relativement explicite.

  • Utilisez flat_map plutôt que map + flatten.

    # mauvais
    all_songs = users.map(&:songs).flatten.uniq
    
    # bien
    all_songs = users.flat_map(&:songs).uniq

Commentaires

Un code de qualité constitue sa propre documentation. Quand vous êtes sur le point d'ajouter un commentaire, demandez-vous, "Comment puis-je améliorer le code pour que ce commentaire ne soit pas nécessaire?" Améliorez le code et documentez le ensuite pour le rendre encore plus limpide.
-- Steve McConnell

  • Ecrivez du code auto-documenté et ignorez le reste de cette section. Vraiment!

  • Les commentaires doivent toujours être écrits en anglais pour éviter les problèmes liés aux caractères spéciaux.

  • La capitalisation et la ponctuation doivent être appliquées aux commentaires de plus d'un mot. Utilisez un espace après les virgules.

  • Evitez les comemntaires superflus.

    # mauvais
    counter += 1 # incrémente le compteur de 1
  • Tenez à jour les commentaires existants. Un commentaire obsolète est pire que pas de commentaire du tout.

Un bon code est comme une bonne blague - il n'a pas besoin d'explication.
-- Russ Olsen

  • Evitez d'écrire des commentaires pour expliquer un mauvais code. Refactorisez ce code pour le rendre explicite.(Fais-le, ou ne le fais pas, mais il n'y a pas d'essai. --Yoda)

Commentaires d'annotation

  • Les annotations devraient généralement être écrites à la ligne juste au dessus du code concerné.

  • Les mots-clés d'annotation sont suivis par deux points et un espace, suivis d'une note décrivant le problème.

  • Si plusieurs lignes sont nécessaires pour décrire le problème, les lignes suivantes doivent être indentées de deux espaces après le #.

    def bar
      # FIXME: This has crashed occasionally since v3.2.1. It may
      #   be related to the BarBazUtil upgrade.
      baz(:quux)
    end
  • Si le problème est tellement évident que toute documentation serait redondante, les annotations peuvent être laissées à la fin de la ligne concernée sans description. Cet usage doit être l'exception et non la règle.

    def bar
      sleep 100 # OPTIMIZE
    end
  • Utilisez TODO pour marquer les fonctionnalités manquantes ou qui devraient être ajoutées ultérieurement.

  • Utilisez FIXME pour signaler un code erroné qui doit être corrigé.

  • Utilisez OPTIMIZE pour signaler un code lent ou inefficace pouvant poser des problèmes de performance.

  • Utilisez HACK pour signaler un code qui semble être issu de pratiques d'écriture douteuses qui devrait être refactorisé.

  • Utilisez REVIEW pour signaler toute chose devant être vérifiée pour confirmer qu'elle fonctionne comme prévu. Par exemple: REVIEW: Are we sure this is how the client does X currently?

  • Utilisez d'autres mots clés d'annotation personnalisés si vous considérez que c'est approprié, mais assurez-vous de les documenter dans le README de votre projet.

Classes

  • Quand vous concevez des hiérarchies de classes, assurez-vous qu'elles sont conformes au Principe de substitution de Liskov.

  • Essayez de rendre vos classes aussi SOLIDES que possible.

  • Fournissez toujours une méthode to_s appropriée aux classes qui représentent des objets de domaine.

    class Person
      attr_reader :first_name, :last_name
    
      def initialize(first_name, last_name)
        @first_name = first_name
        @last_name = last_name
      end
    
      def to_s
        "#@first_name #@last_name"
      end
    end
  • Utilisez la famille de fonctions attr pour définir des accesseurs de lecture ou d'écriture.

    # mauvais
    class Person
      def initialize(first_name, last_name)
        @first_name = first_name
        @last_name = last_name
      end
    
      def first_name
        @first_name
      end
    
      def last_name
        @last_name
      end
    end
    
    # bien
    class Person
      attr_reader :first_name, :last_name
    
      def initialize(first_name, last_name)
        @first_name = first_name
        @last_name = last_name
      end
    end
  • Pensez à utiliser Struct.new, qui définit les accesseurs triviaux, constructeurs et operateurs de comparaison pour vous.

    # bien
    class Person
      attr_reader :first_name, :last_name
    
      def initialize(first_name, last_name)
        @first_name = first_name
        @last_name = last_name
      end
    end
    
    # meilleur
    class Person < Struct.new(:first_name, :last_name)
    end
  • Pensez à ajouter des méthodes de fabrique pour faciliter la création d'instances d'une classe donnée.

    class Person
      def self.create(options_hash)
        # contenu omis
      end
    end
  • Privilégiez le duck-typing plutôt que l'héritage.

    # mauvais
    class Animal
      # méthode abstraite
      def speak
      end
    end
    
    # extension de la superclass
    class Duck < Animal
      def speak
        puts 'Quack! Quack'
      end
    end
    
    # extension de la superclass
    class Dog < Animal
      def speak
        puts 'Bau! Bau!'
      end
    end
    
    # bien
    class Duck
      def speak
        puts 'Quack! Quack'
      end
    end
    
    class Dog
      def speak
        puts 'Bau! Bau!'
      end
    end
  • Evitez l'utilisation des variables de classe (@@) à cause de leur comportement pénible avec l'héritage.

    class Parent
      @@class_var = 'parent'
    
      def self.print_class_var
        puts @@class_var
      end
    end
    
    class Child < Parent
      @@class_var = 'child'
    end
    
    Parent.print_class_var # => va écrire "child"

    Comme vous pouvez le voir, toutes les classes de la hiérarchie partagent en fait la même variable de classe. Les variables d'instance de classe devraient généralement être privilégiées à la place des variables de classe.

  • Affectez aux méthodes les niveaux de visibilité (private, protected) appropriés conformément à leur utilisation attendue. Ne laissez pas tout en public (par défaut). Après tout, nous codons en Ruby là, pas en Python.

  • Indentez les méthodes public, protected, et private au même niveau que les définitions de methodes auxquelles elles s'appliquent. Passez une ligne au dessus du modificateur de visibilité et une ligne en dessous de façon à accentuer le fait qu'il s'applique à toutes les méthodes qui le suivent.

    class SomeClass
      def public_method
        # ...
      end
    
      private
    
      def private_method
        # ...
      end
    
      def another_private_method
        # ...
      end
    end
  • Utilisez def self.method pour définir les méthodes singleton. Cela rend le code plus facile à refactoriser car le nom de la classe n'est pas répété.

    class TestClass
      # mauvais
      def TestClass.some_method
        # contenu omis
      end
    
      # bien
      def self.some_other_method
        # contenu omis
      end
    
      # Egalement possible et pratique quand vous
      # devez définir plusieurs méthodes singleton.
      class << self
        def first_method
          # contenu omis
        end
    
        def second_method_etc
          # contenu omis
        end
      end
    end

Exceptions

  • Signalez les exceptions en utilisant la méthode fail. Utilisez raise uniquement lorsque vous capturez une exception et la levez à nouveau (parcequ'il ne s'agit pas d'un échec mais d'une levée d'exception explicite et intentionnelle).

    begin
      fail 'Oops';
    rescue => error
      raise if error.message != 'Oops'
    end
  • Ne jamais utiliser return dans un bloc ensure. Cela donnerait la priorité au retour sur une éventuelle levée d'exception, et la méthode retournerait un résultat comme si aucune exception n'avait été levée. En fait, l'exception serait ignorée silencieusement.

    def foo
      begin
        fail
      ensure
        return 'very bad idea'
      end
    end
  • Utilisez des blocs begin implicites autant que possible.

    # mauvais
    def foo
      begin
        # algorithme principal
      rescue
        # gestion d'échec
      end
    end
    
    # bien
    def foo
      # algorithme principal
    rescue
      # gestion d'échec
    end
  • Limitez la prolifération des blocs begin en utilisant les méthodes de contingence (un terme inventé par Avdi Grimm.)

    # mauvais
    begin
      something_that_might_fail
    rescue IOError
      # handle IOError
    end
    
    begin
      something_else_that_might_fail
    rescue IOError
      # handle IOError
    end
    
    # bien
    def with_io_error_handling
       yield
    rescue IOError
      # handle IOError
    end
    
    with_io_error_handling { something_that_might_fail }
    
    with_io_error_handling { something_else_that_might_fail }
  • Ne supprimez pas les exceptions.

    # mauvais
    begin
      # une exception se produit ici
    rescue SomeError
      # la section de secours ne fait absolument rien
    end
    
    # mauvais
    do_something rescue nil
  • Evitez l'utilisation de rescue sous sa forme de modificateur.

    # mauvais - cela capture toutes les exceptions StandardError
    do_something rescue nil
  • N'utilisez pas d'exception pour le flux de contrôle.

    # mauvais
    begin
      n / d
    rescue ZeroDivisionError
      puts 'Cannot divide by 0!'
    end
    
    # bien
    if d.zero?
      puts 'Cannot divide by 0!'
    else
      n / d
    end
  • Evitez rescue Exception. Cela aurait pour effet d'intercepter les signaux et appels à exit, et nécesiterait de kill -9 le processus.

    # mauvais
    begin
      # les appels de signaux exit et kill sont interceptés (sauf kill -9).
      exit
    rescue Exception
      puts "vous ne vouliez pas vraiment arrêter, pas vrai?"
      # gestion d'exception
    end
    
    # bien
    begin
      # un rescue par défaut intercepte les exceptions StandardError et non Exception,
      # contrairement à ce que pensent beaucoup de développeurs.
    rescue => e
      # gestion d'exception
    end
    
    # bien aussi
    begin
      # une exception se produit ici
    
    rescue StandardError => e
      # gestion d'exception
    end
  • Placez les exceptions spécifiques en haut de la chaine d'interception, sans quoi elle ne seront jamais interceptées.

    # mauvais
    begin
      # du code
    rescue Exception => e
      # gestion d'exception
    rescue StandardError => e
      # gestion d'exception
    end
    
    # bien
    begin
      # du code
    rescue StandardError => e
      # gestion d'exception
    rescue Exception => e
      # gestion d'exception
    end
  • Libérez les ressources externes ouvertes par votre programme dans un bloc ensure.

    f = File.open('testfile')
    begin
      # .. processus
    rescue
      # .. gestion d'erreur
    ensure
      f.close unless f.nil?
    end
  • Privilégiez l'utilisation d'exceptions standards plutôt que d'introduire de nouvelles classes d'exception.

Collections

  • Privilégiez la notation littérale pour créer des tableaux ou des hashs. (sauf si vous devez passer des paramètres à leurs constructeurs).

    # mauvais
    arr = Array.new
    hash = Hash.new
    
    # bien
    arr = []
    hash = {}
  • Privilégiez %w à la syntaxe littérale de création de tableau quand vous avez besoin d'un tableau de chaines de caractères.

    # mauvais
    STATES = ['draft', 'open', 'closed']
    
    # bien
    STATES = %w(draft open closed)
  • Evitez de créer des écarts énormes dans les tableaux.

    arr = []
    arr[100] = 1 # là vous avez un tableau avec plein de nil.
  • Utilisez Set plutôt que Array pour traiter des éléments uniques. Set gère une liste de valeurs non ordonnées sans doublons. C'est un croisement entre les capacités interopérables et intuitives de Array et la recherche rapide de Hash.

  • Privilégiez les symboles plutôt que les chaines de caractères pour les clés de hash.

    # mauvais
    hash = { 'one' => 1, 'two' => 2, 'three' => 3 }
    
    # bien
    hash = { one: 1, two: 2, three: 3 }
  • Evitez d'utiliser des objets modifiables comme clés de hash.

  • Privilégiez la nouvelle notation hash en Ruby 1.9 lorsque vos clés sont des symboles.

    # mauvais
    hash = { :one => 1, :two => 2, :three => 3 }
    
    # bien
    hash = { one: 1, two: 2, three: 3 }
  • Utilisez fetch pour manipuler des clés de hash qui sont censées être présentes.

    heroes = { batman: 'Bruce Wayne', superman: 'Clark Kent' }
    # mauvais - une erreur pourrait ne pas être remarquée
    heroes[:batman] # => "Bruce Wayne"
    heroes[:supermann] # => nil
    
    # bien - fetch génère une exception KeyError, rendant le problème évident
    heroes.fetch(:supermann)
  • Basez-vous sur le fait que les hash en Ruby 1.9 sont ordonnés.

  • Ne jamais modifier une collection en la parcourant.

Chaînes de caractères

  • Privilégiez l'interpolation de chaîne plutôt que la concaténation:

    # mauvais
    email_with_name = user.name + ' <' + user.email + '>'
    
    # bien
    email_with_name = "#{user.name} <#{user.email}>"
  • Pensez à entourer le code interpolé d'un espace. Cela permet de mieux distinguer le code de la chaîne de caractères.

    "#{ user.last_name }, #{ user.first_name }"
  • Privilégiez les chaîne à guillemets simples lorsque vous n'utilisez pas d'interpolation ou de caractères spéciaux comme \t, \n, ', etc.

    # mauvais
    name = "Bozhidar"
    
    # bien
    name = 'Bozhidar'
  • N'utilisez pas {} autour des variables d'instance interpolées dans une chaîne.

    class Person
      attr_reader :first_name, :last_name
    
      def initialize(first_name, last_name)
        @first_name = first_name
        @last_name = last_name
      end
    
      # mauvais
      def to_s
        "#{@first_name} #{@last_name}"
      end
    
      # bien
      def to_s
        "#@first_name #@last_name"
      end
    end
  • Evitez d'utiliser String#+ pour assembler de longues chaînes de caractères. Utilisez plutôt String#<< qui transforme la chaîne sur place et s'avère toujours plus rapide que String#+, qui crée beaucoup de nouveaux objets.

    # bien et rapide
    html = ''
    html << '<h1>Page title</h1>'
    
    paragraphs.each do |paragraph|
      html << "<p>#{paragraph}</p>"
    end

Expressions rationnelles

Certaines personnes se disent, lorsqu'elles sont confrontées à un problème "Je sais, je vais utiliser les expressions rationnelles." Et elles se retrouvent avec deux problèmes.
-- Jamie Zawinski

  • N'utilisez pas d'expression rationnelle pour une simple recherche de texte en clair dans une chaîne de caractères: string['text']

  • Pour des situations simples, vous pouvez utiliser la regexp directement dans l'index de chaîne.

    match = string[/regexp/]             # récupère le contenu correspondant à la regexp
    first_group = string[/text(grp)/, 1] # récupère le contenu du groupe capturé
    string[/text (grp)/, 1] = 'replace'  # string => 'text replace'
  • Utiliser les groupes non capturants quand vous n'utilisez pas le résultat capturé par les parenthèses.

    /(first|second)/   # mauvais
    /(?:first|second)/ # bien
  • Evitez d'utiliser $1-9 car il peut être difficile de déterminer ce qu'ils contiennent. Les groupes nommés peuvent être utilisés à la place.

    # mauvais
    /(regexp)/ =~ string
    ...
    process $1
    
    # bien
    /(?<meaningful_var>regexp)/ =~ string
    ...
    process meaningful_var
  • Les classes de caractères comportent juste quelques caractères spéciaux dont vous devez vous soucier: ^, -, \, ], alors n'échappez pas . ou les crochets dans [].

  • Faites attention avec ^ et $ car ils correspondent aux débuts et fins de lignes, pas de la chaîne. Si vous cherchez une correspondance avec la chaîne entière, utilisez \A et \z (à ne pas confondre avec \Z qui est l'équivalent de /\n?\z/).

    string = "some injection\nusername"
    string[/^username$/]   # correspondance
    string[/\Ausername\z/] # pas de correspondance
  • Utilisez le modificateur x pour les regexps complexes. Cela les rend plus lisibles et vous pouvez ajouter des commentaires utiles. Faites juste attention aux espaces qui sont ignorés.

    regexp = %r{
      start         # du texte
      \s            # un caractère d'espacement
      (group)       # premier groupe
      (?:alt1|alt2) # une alternative
      end
    }x
  • Pour des remplacements complexes, sub/gsub peuvent être utilisés avec un bloc ou un hash.

Notations pourcents

  • Utilisez %w à vonlonté.

    STATES = %w(draft open closed)
  • Utilisez %() pour les chaînes à simple ligne qui nécessitent à la fois une interpolation et l'inclusion de doubles guillemets. Pour les chaînes multi-lignes, privilégiez les heredocs.

    # mauvais (pas besoin d'interpolation)
    %(<div class="text">Some text</div>)
    # devrait être '<div class="text">Some text</div>'
    
    # mauvais (pas de double guillemet)
    %(This is #{quality} style)
    # should be "This is #{quality} style"
    
    # mauvais (multi-lignes)
    %(<div>\n<span class="big">#{exclamation}</span>\n</div>)
    # should be a heredoc.
    
    # bien (interpolation, doubles guillemets, simple ligne)
    %(<tr><td class="name">#{name}</td>)
  • Utilisez %r uniquement pour les expressions régulières recherchant plus d'un caractère '/'.

    # mauvais
    %r(\s+)
    
    # encore mauvais
    %r(^/(.*)$)
    # should be /^\/(.*)$/
    
    # bien
    %r(^/blog/2011/(.*)$)
  • Evitez %q, %Q, %x, %s, and %W.

  • Privilégiez () comme délimiteurs pour toutes les notations %.

Méta-programmation

  • Evitez la méta-programmation inutile.

  • Ne modifiez pas le comportement des classes du noyau lorsque vous écrivez des librairies. (Ne leur appliquez pas de "monkey-patch")

  • La forme de bloc de class_eval est préférable à la form de chaîne interpolée.

    • Quand vous utilisez une chaîne interpolée, fournissez toujours __FILE__ et __LINE__, de sorte que vos piles d'exécution aient du sens:

      class_eval 'def use_relative_model_naming?; true; end', __FILE__, __LINE__
    • define_method est préférable à class_eval{ def ... }

  • Lorsque vous utilisez class_eval (ou tout autre eval) avec une chaîne interpolée, ajoutez un bloc de commentaire montrant son apparence une fois interpolée (c'est une pratique que j'ai apprise dans le code source de Rails):

    # from activesupport/lib/active_support/core_ext/string/output_safety.rb
    UNSAFE_STRING_METHODS.each do |unsafe_method|
      if 'String'.respond_to?(unsafe_method)
        class_eval <<-EOT, __FILE__, __LINE__ + 1
          def #{unsafe_method}(*args, &block)       # def capitalize(*args, &block)
            to_str.#{unsafe_method}(*args, &block)  #   to_str.capitalize(*args, &block)
          end                                       # end
    
          def #{unsafe_method}!(*args)              # def capitalize!(*args)
            @dirty = true                           #   @dirty = true
            super                                   #   super
          end                                       # end
        EOT
      end
    end
  • Evitez d'utilisez method_missing pour la méta-programmation. Cela complexifie les piles d'exécution; le comportement n'est pas listé dans #methods; les appels de méthodes mal orthographiés pourraient fonctionner sans générer d'erreur (nukes.launch_state = false). Pensez à utiliser la délégation, la procuration ou define_method à la place. Si vous devez vraiment utiliser method_missing:

    • Définissez également respond_to_missing?

    • Interceptez seulement les méthodes comportant un préfixe bien défini, comme find_by_* -- rendez votre code aussi robuste que possible.

    • Appelez super à la fin de votre traitement.

    • Déléguez vers des méthodes robustes et non-magiques:

      # mauvais
      def method_missing?(meth, *args, &block)
        if /^find_by_(?<prop>.*)/ =~ meth
          # ... beaucoup de code pour faire un find_by
        else
          super
        end
      end
      
      # bien
      def method_missing?(meth, *args, &block)
        if /^find_by_(?<prop>.*)/ =~ meth
          find_by(prop, *args, &block)
        else
          super
        end
      end
      
      # La meilleure solution serait cependant d'utiliser define_method pour chaque attribut
      # utilisable au travers de la méthode find_by.

Divers

  • Ecrivez du code ruby sécurisé grace à ruby -w.

  • Evitez les hashs comme paramètres optionnels. La méthode n'en ferait-elle pas trop ?

  • Evitez les méthodes de plus de 10 lignes de code (sans compter les lignes vides). Idéalement, la plupart des méthodes devraient faire moins de 5 lignes.

  • Evitez les listes de paramètres plus longues que trois ou quatre paramètres.

  • Si vous avez vraiment besoin de méthodes "globales", ajoutez les au noyau en tant que méthodes privées.

  • Utilisez les variables d'instances de classe plutôt que des variables globales

    # mauvais
    $foo_bar = 1
    
    # bien
    class Foo
      class << self
        attr_accessor :bar
      end
    end
    
    Foo.bar = 1
  • Evitez d'utiliser alias quand vous pouvez utiliser alias_method.

  • Utilisez OptionParser pour analyser des options de ligne de commande complexes et ruby -s pour des options de ligne de commande simples.

  • Codez de manière fonctionnelle, en évitant la mutation autant que possible.

  • Ne modifiez pas les arguments sauf si c'est l'objectif de la méthode.

  • Evitez les imbrications de blocs sur plus de trois niveaux.

  • Soyez cohérent. Dans un monde idéal, soyez cohérent avec ces lignes directrices.

  • Utilisez votre bon sens.

Contribuer

Rien de ce qui est écrit dans ce guide n'est gravé dans le marbre. Mon but est que nous travaillions ensemble avec toutes les personnes intéressées par le style de programmation Ruby, de telle sorte que nous puissions créer une ressource qui serait bénéfique à l'ensemble de la communauté Ruby.

N'hésitez pas à ouvrir des tickets ou d'envoyer des 'pull-requests' avec vos améliorations. Merci d'avance pour votre aide!

Passez le mot

Un guide piloté par la communauté n'apportera pas grand chose à une communauté qui n'est pas au courant de son existence. Tweetez à propos du guide, partagez le avec vos amis et collègues. Chaque commentaire, chaque suggestion ou opinion que nous recevons rendra le guide encore meilleur. Et ce que nous voulons, c'est avoir le meilleur guide possible, n'est-ce pas?