ruby-****@sourc*****
ruby-****@sourc*****
2003年 10月 5日 (日) 01:23:55 JST
-------------------------
REMOTE_ADDR = 218.231.205.39
REMOTE_HOST =
URL = http://ruby-gnome2.sourceforge.jp/?Naming+and+Conversion+Rules
-------------------------
= Ruby-GNOME2 naming/conversion rules
You should conform to this document when implementing Ruby-GNOME components.
Since this document is not yet complete, do not hesitate to ask questions to the mailing list.
== Library names
Ruby-GNOME2 means the whole project.
If you want to talk about a Ruby-GNOME2 component, use "/". Examples:
* Ruby/GNOME - gnome2 module
* Ruby/GnomeCanvas - gnomecanvas2 module
* Ruby/GTK - gtk2 module
* Ruby/GLib - glib2 module (glib2 is always required by other libraries)
* Ruby/Libglade - libglade module
You also can say as Ruby/GNOME2, Ruby/GTK2, if you need to make the distinction between the actual framework (Ruby-GNOME2) and the old one (Ruby-GNOME, based on GTK+1.2).
== Accessors (Setter/Getter methods)
There are two patterns. In each pattern, you should implement all the methods.
* Method has only one argument
setter: hoge=(a) # Return a.
set_hoge(a) # Return self.
getter: hoge # Return hoge's value.
* Method has 2 or more arguments
setter: set_fuga(a, b) # Return self.
getter: fuga # Have no argument. Return fuga's value.
get_fuga(a, b) # Have arguments. Return fuga's value.
== is_* methods
Convert is_foo -> foo?, since it is more natural in Ruby.
== has_*, use_* methods
If the method return gboolean, add '?' to the end of the name of the method.
has_foo -> has_foo?
use_bar -> use_bar?
== set/get_has_*, set/get_use_* methods
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 ...
There are some methods which don't start with a verb like set/get/is/has/use. We think these patterns are not good naming. But we don't convert (remove verbs) like as follows.
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?
== Destructive methods(which changes the object itself)
Usually, destructive methods have a "!" at the end of their name. For example, Gtk::TreeIter#first!, #next!, Gtk::TreePath#prev!, #next!, #up!, #down!.
(*) Note that '!' in Ruby means "careful", or "dangerous". It's used to alert the programmer.
== *_foreach methods
Convert them to 'each'.
== list_foos methods
If it returns an array which is converted from GList or GSList, rename them to 'foos'.
== The methods which return boolean variable
Add '?' to end of the name of method (example: foo -> foo?), if the method aims to return a value.
For example:
do_something -> do_something # Do something, as result, return gboolean.
some_status -> some_status? # Get statuses or properties.
== Instance methods which return void
Return self.
== initialize
Return Qnil.
== Class methods/Module methods which return void
Return Qnil.
== Constants
Sometimes this definition is difficult. When you are confused about this, you should ask on the mailing list.
* If the constants belong to an object (class or module), include the constants among members of the object.
For example, in the case of 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
* The constants are independant from objects (Almost in 'Standard Enumerations'):
GTK_FOO_BAR -> Gtk::FOO_BAR
== Classes, Modules and Methods
Usually a C structure is mapped into a ruby class. But if there is no C structure, you may implement the group as a Ruby module.
There is also an exception: methods that first argument is other class's instance. In this case, it may be better to implement the method in the other class.
== Plural methods which have the same meaning but accept different arguments
Combine them in a single method.
== Miscellaneous
* You can add new methods which do not exist in the C library.
* You can rename some functions of the C library, to make them more natural from Ruby.
These points are not forbidden, because Ruby-GNOME2 is not just a Ruby wrapper for GNOME/GTK+. But you need to propose your idea to the mailing list before.
- - ((<Masao>))
+ === ChangeLog
+ :2003-10-05 Add list_foos rule ((<Masao>))