Créer  Editer  FrontPage  Index  Chercher  Changements  History  RSS  Login

Conventions et regles de nommage

Conventions et règles de nommage

Vous devez vous conformer à ce document si vous implémentez un composant pour Ruby-GNOME2.

Noms des bibliothèques

Le projet s'appelle Ruby-GNOME2.

Pour parler d'une extension de Ruby-GNOME2, utilisez le "/". Par exemple:

  • Ruby/GNOME - Module gnome2
  • Ruby/GnomeCanvas - Module gnomecanvas2
  • Ruby/GTK - Module gtk2
  • Ruby/GLib - Module glib2 (glib2 est nécessaire et automatiquement chargé par les autres bibliothèques)
  • Ruby/Libglade - Module libglade

Vous pouvez également parler de Ruby/GNOME2, Ruby/GTK2, si vous devez faire la distinction avec la première génération Ruby-GNOME (qui utilisait Gtk+1.2).

Méthodes d'accès (set/get)

Il y a deux possibilités. Dans tous les cas, vous devez implémenter toutes les méthodes.

  • La méthode n'a qu'un seul argument
set: hoge=(a)             # retourne a.
     set_hoge(a)          # retourne self.
get: hoge                 # retourne la valeur de hoge.
  • la méthode à 2 ou plusieurs arguments
set: set_fuga(a, b)       # retourne self.
get: fuga                 # pas d'arguments, retourne la valeur de fuga.
     get_fuga(a, b)       # avec arguments, retourne la valeur de fuga.

Méthodes is_*

Renommez-les en *?. Par exemple pour is_foo, il convient mieux d'utiliser à la place foo?. C'est beaucoup plus naturel en Ruby.

Méthodes has_*, use_*

Si la méthode retourne un gboolean, rajoutez simplement '?' à la fin de son nom.

has_foo -> has_foo?
use_bar -> use_bar?

Méthodes set/get_has_*, set/get_use_*

get_has_foo -> has_foo?
set_has_foo -> has_foo=(a), set_has_foo(a)
get_use_foo -> use_foo?
set_use_foo -> use_foo=(a), set_use_foo(a)

classname_foo_set_bar, classname_foo_get_bar ...

Il existe des méthodes dont le nom ne commence pas par set/get/is/has/use. Nous pensons que ces méthodes n'ont pas été nommées correctement (le nom est très important). Toutefois, nous ne les convertissons pas comme ceci:

gtk_classname_foo_set_bar -> Gtk::ClassName#foo_set_bar
gtk_classname_foo_get_bar -> Gtk::ClassName#foo_get_bar
gtk_classname_foo_get_bar -> Gtk::ClassName#foo_get_bar?
gtk_classname_foo_is_bar -> Gtk::ClassName#foo_is_bar?
gtk_classname_foo_has_bar -> Gtk::ClassName#foo_has_bar?
gtk_classname_foo_use_bar -> Gtk::ClassName#foo_use_bar?

initialize

Retournez Qnil.

Méthodes dites destructive (qui modifient l'objet en lui-même)

Généralement, le nom des méthodes destructives se termine par '!'. Par exemple, Gtk::TreeIter#first!, #next!, Gtk::TreePath#prev!, #next!, #up!, #down!.

(*) Notez que '!' à plutot une connotation "dangereuse" que "destructive", qui sert à alerter le programmeur.

Méthodes *_foreach

Renommez-les en 'each'.

Méthodes list_foos

Si une méthode retourne un tableau dont le contenu est initialisé à partir d'une structure GList ou GSList, alors renommez-la en 'foos'.

Méthodes qui retournent une valeur booléenne

Ajoutez '?' à la fin du nom de la méthode (par exemple, foo -> foo?) en fonction de ce dernier. Certaines méthodes insistent plus sur une action particulière à effectuer que sur le renvoi d'une valeur de status.

Exemple:

do_something -> do_something  # Fait quelque chose, et retourne un booléan.
some_status -> some_status?   # Retourne simplement un booléan.

Constantes

Quelquefois définir des constantes peut se révéler difficile. Dans le doute, demandez sur la liste de diffusion.

  • Si les constantes sont liés à un objet (classe ou module) particulier, renommez-les alors d'une façon significative. Par exemple, dans le cas de GtkDialog:

    GtkDialogFlags
       GTK_DIALOG_MODAL               -> Gtk::Dialog::MODAL
       GTK_DIALOG_DESTROY_WITH_PARENT -> Gtk::Dialog::DESTROY_WITH_PARENT
       GTK_DIALOG_NO_SEPARATOR        -> Gtk::Dialog::NO_SEPARATOR
    
    GtkResponseType
       GTK_RESPONSE_NONE     ->  Gtk::Dialog::RESPONSE_NONE
       GTK_RESPONSE_REJECT   ->  Gtk::Dialog::RESPONSE_REJECT
       GTK_RESPONSE_ACCEPT   ->  Gtk::Dialog::RESPONSE_ACCEPT
  • Si les constantes sont radicalement indépendantes d'un objet particulier ('Standard Enumerations'):

    GTK_FOO_BAR -> Gtk::FOO_BAR

Classes, Modules et Methodes

En temps normal, une classe Ruby encapsule une structure C. Si il n'existe pas de structure C, vous devriez alors envisager d'implémenter le groupe comme un module Ruby.

Il existe également quelques exceptions, c'est-à-dire des méthodes dont le premier argument est une instance d'une autre classe. Dans ce cas, implémentez alors la méthode dans l'autre classe.

Divers

  • Vous pouvez ajouter des méthodes qui n'existent pas dans la bibliothèque C si vous le désirez.
  • Vous pouvez changer le nom de certaines fonctions de la bibliothèque C, si vous pensez que la méthode paraîtra plus naturelle dans Ruby.

Ces choses ne sont pas interdites, car Ruby-GNOME2 n'est pas qu'un simple "emballage" GNOME pour Ruby. Mais proposez toutefois votre idée sur la liste de diffusion.

ChangeLog

2003-10-05 Ajout de la règle list_foos Masao

Page traduite de l'anglais par Laurent Sansonetti.

Dernière modification:2011/06/06 08:03:46
Mots clef:
Références:[FrontPage]