Erstellen  Editieren  FrontPage  Index  Suchen  Veränderungen  Verlauf  RSS  Login

Naming and Conversion Rules

Richtlinien der Namensgebung

Sie sollten sich an diesem Dokument orientieren, wenn Sie Komponenten für Ruby-GNOME implementieren.

Bibliotheksnamen

Ruby-GNOME2 steht für das gesamte Projekt.

Wenn Sie über eine Ruby-GNOME2-Komponente sprechen, benutzen Sie "/". Als Beispiele:

  • Ruby/GNOME - Modul gnome2
  • Ruby/GnomeCanvas - Modul gnomecanvas2
  • Ruby/GTK - Modul gtk2
  • Ruby/GLib - Modul glib2 (glib2 wird immer von anderen Bibliotheken verwendet)
  • Ruby/Libglade - Modul libglade

Sie können auch Ruby/GNOME2 oder Ruby/GTK2 schreiben, wenn sie den Unterschied zwischen dem aktuellen Framework (Ruby-GNOME2) und der alten Version (Ruby-GNOME, basierend auf GTK+ 1.2) deutlich machen wollen.

Klassen- und Modulnamen

Üblicherweise ist ein Ruby-Objekt auf ein C-Struct gemappt. Es wird nach dem ersten Präfix getrennt.

Wir trennen nicht nach diesem Muster:

  • GtkTextView -> Gtk::Text::View? (NG)
  • GnomeDruidPageEdge -> Gnome::Druid::Page::Edge? (NG)

Auch nicht nach diesem:

  • GdkGLWindow -> GdkGL::Window (NG)
  • GnomeCanvasItem -> GnomeCanvas::Item (NG)

Es gibt einige Ausnahmen:

  • GObject -> GLib::Object
  • GnomeVFSDirectory -> GnomeVFS::Directory
  • HtmlDocument(Ruby/GtkHtml2) -> Gtk::HtmlDocument?

Wenn es kein ernstes Problem gibt, verwenden Sie einfach den allgemeinen Weg.

Akzessoren (Setter-/Getter-Methoden)

Es gibt zwei Muster, in jedem davon sollten Sie alle Methoden implementieren.

  • Die Methode hat nur ein Argument.
Setter: hoge=(a)             # Gibt a zurück.
        set_hoge(a)          # Gibt self zurück.
Getter: hoge                 # Gibt den Wert von hoge zurück.
  • Die Methode hat 2 oder mehr Argumente.
Setter: set_fuga(a, b)       # Gibt self zurück.
Getter: fuga                 # Hat keine Argumente. Gibt den Wert von fuga zurück.
        get_fuga(a, b)       # Hat Argumente. Gibt den Wert von fuga zurück.

is_*-Methoden

Benutzen Sie statt "is_foo" lieber "foo?", es entspricht eher dem Ruby-Stil.

has_*-, use_*-Methoden

Wenn eine Methode einen booleschen Wert oder einen Wert vom Typ gboolean zurückgibt, fügen Sie dem Methodennamen noch ein ? an.

has_foo -> has_foo?
use_bar -> use_bar?

set/get_has_*-, set/get_use_*-Methoden

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 ...

Es gibt ein paar Methoden, die nicht mit einem Verb wie set, get, is, has oder use beginnen. Wir halten diese Muster nicht für gute Benennungen. Aber wir entfernen auch nicht die Verben aus ihnen, wie in den folgenden Beispielen.

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?

Destruktive Methoden (die das Objekt selbst ändern)

Üblicherweise haben destruktive Methoden ein ! am Ende ihres Namens. Beispielsweise Gtk::TreeIter#first!, #next!, Gtk::TreePath#prev!, #next!, #up!, #down!.

(*) Beachten Sie, dass '!' am Ende einer Ruby-Methode für "Vorsicht" oder "gefährlich" steht. Es wird benutzt, um den Programmierer darüber zu informieren, dass diese Methode das Objekt selbst ändert.

*_foreach-Methoden

Ändern Sie sie zu 'each'.

list_foos-Methoden

If it returns an array which is converted from GList or GSList, rename them to 'foos'.

initialize

Return Qnil.

Konstanten

Manchmal ist diese Definition etwas schwierig. Wenn Sie nicht sicher sind, fragen Sie in der Mailing-Liste.

  • Wenn die Konstanten zu einem Objekt gehören (Klasse oder Modul), binden Sie die Konstanten in die Member des Objektes ein. Am Beispiel von GtkDialog sieht das so aus:

    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
  • Die Konstanten sind unabhängig von Objekten:

    GTK_FOO_BAR -> Gtk::FOO_BAR

Klassen, Module und Methoden

Üblicherweise ist ein C-Struct in eine Ruby-Klasse gemappt. Aber wenn es kein C-Struct gibt, können Sie die Gruppe als Ruby-Modul implementieren. Hier gibt es eine Ausnahme: Methoden, dessen erstes Argument eine andere Klasseninstanz ist. In diesem Fall ist es besser, die Methode in der anderen Klasse zu implementieren.

Verschiedenes

  • Sie können neue Methoden hinzufügen, die noch nicht in der C-Bibliothek existieren.
  • Sie können einige Funktionen der C-Bibliotheken umbenennen, um sie mehr an den Ruby-Stil anzupassen.

Diese Punkte sind nicht verboten, denn Ruby-GNOME2 ist nicht nur ein Ruby-Wrapper für GNOME oder GTK+. Aber bitte schreiben Sie Ihre Verbesserungsvorschläge vorher in die Mailing-Liste.

ChangeLog

2003-10-11 Masao?
Add Class/Modlue names.
2003-10-05 Masao?
Add list_foos rule.
Zuletzt geändert:2004/04/07 03:07:42
Stichworte:
Referenzen:[FrontPage]