ruby-****@sourc*****
ruby-****@sourc*****
2003年 8月 15日 (金) 22:21:40 JST
-------------------------
REMOTE_ADDR = 217.117.54.155
REMOTE_HOST =
URL = http://ruby-gnome2.sourceforge.jp/?Naming+and+Conversion+Rules
-------------------------
= Ruby-GNOME2 naming/conversion rules
- Implementing Ruby-GNOME components, you should conform to this document. But this has never been complete yet. If you have any suggestion, mail to Ruby-GNOME2 Mailing list.
+ 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 whole of the project.
+ Ruby-GNOME2 means the whole project.
- If you say a part of Ruby-GNOME2, use "/".
+ 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 other libraries)
- * Ruby/Libglade - libglade
+ * Ruby/GLib - glib2 module (glib2 is always required by other libraries)
+ * Ruby/Libglade - libglade module
- You also can say as Ruby/GNOME2, Ruby/GTK2.
- This is used when you restrict it against Ruby-GNOME(GTK+1.2based).
+ 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)
+ == Accessors (Setter/Getter methods)
- There are two patterns. In each patterns, you should implement all methods.
+ There are two patterns. In each pattern, you should implement all the methods.
- * Method has An argument
+ * Method has only one argument
- setter: hoge=(a) #return a.
- set_hoge(a) #return self.
- getter: hoge #return hoge's value.
+ setter: hoge=(a) # Return a.
+ set_hoge(a) # Return self.
+ getter: hoge # Return hoge's value.
- * Method has more than 2 arguments
+ * Method has 2 or more arguments
- setter: set_fuga(a, b) #return self.
- getter: fuga #Have no arguments. return fuga's value.
- get_fuga(a, b) #Have arguments. return fuga's value.
+ 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?. Because it is more natural in Ruby.
+ 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 word.
+ If the method return gboolean, add '?' to the end of the name of the method.
has_foo -> has_foo?
use_bar -> use_foo?
== 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 verb like set/get/is/has/use. We think these pattern is not good naming. But we don't convert(remove verbs) like as follows.
+ 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?
== Instance methods which return void
Return self.
== initialize
Return Qnil.
== Class methods/Module methods which return void
Return Qnil.
== Destructive methods(which changes the object itself)
- Usually destructive methods add "!" to the end of the words. For example, Gtk::TreeIter#first, #next!, Gtk::TreePath#prev!, #next!, #up!, #down!.
+ Usually, destructive methods have a "!" at the end of their name. For example, Gtk::TreeIter#first!, #next!, Gtk::TreePath#prev!, #next!, #up!, #down!.
- (*) Strictly, '!' doesn't express not destructive but "careful or more dangerous"
+ (*) Note that '!' in Ruby means "careful", or "dangerous". It's used to alert the programmer.
== *_foreach methods
- Convert it to 'each'.
+ Convert them to 'each'.
== The methods which return boolean variable
- Add '?' to end of method. ex) foo -> foo?.
- But some methods which don't aim to get return value, you should not add '?'.
+ Add '?' to end of the name of method (example: foo -> foo?), if the method aims to return a value.
- do_something -> do_something #Do something, as result, return gboolean.
- some_status -> some_status? #Get statuses or properties.
+ For example:
+ do_something -> do_something # Do something, as result, return gboolean.
+ some_status -> some_status? # Get statuses or properties.
+
== Constants
- Sometimes this definition is difficult. When you confuse how to implement about constants, you should ask it to ML.
+ Sometimes this definition is difficult. When you are confused about this, you should ask on the mailing list.
* Abolish Constants module. e.g. Gtk::ItemFactory::Constants.
- * If the constants belong an object(class or module) obiviouly, include the constants among members of the object.
+ * 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:
- e.g.)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 is independant from objects(Almost in 'Standard Enumerations').
+ * The constants are independant from objects (Almost in 'Standard Enumerations'):
GTK_FOO_BAR -> Gtk::FOO_BAR
== Classes, Modules and Methods
- Usually a C Struct is mapping a ruby class. But if there are no C Struct, you may implement the group as module.
+ 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.
- By way of exception, some methods that first argument is other class's instance may be better to implement to other class.
+ 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 are same meaning but arguments are different
- Combine them in a method.
+ == Plural methods which have the same meaning but accept different arguments
+ Combine them in a single method.
== Miscellaneous
- * Add new method which does not exist in C library but you want.
- * Change C library's function name more naturally as method name of Ruby.
+ * 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.
- They are not forbidden in Ruby-GNOME2. Because Ruby-GNOME2 is not just only wrapper for GNOME/GTK+. But they are not recommanded way, so it is better to ask ML about it.
+ These points are not forbidden, because Ruby-GNOME2 is not just a Ruby wrapper for GNOME/GTK+. But you should propose your idea to the mailing list before.
- ((<Masao>))