Re: [Wxruby-dev] Summary of naming problems

[Richard Kilmer]

On Sunday, June 22, 2003, at 01:59  PM, Kevin Smith wrote:

> Ok. I've tried to figure out a way out of all of this. So I laid out 
> all
> the naming problems that I'm aware of right now. Here are the C++
> wxWindows naming categories I've found, with examples:
>
> CLASS
>  wxWindow
>
> CLASS METHOD
>  GetPosition
>
> GLOBAL METHOD
>  wxMessageBox
>  EVT_MENU
>
> CONSTANT, PRE-DEFINED OBJECT, PTR TO PRE-DEFINED OBJECT
>  wxSUNKEN_BORDER
>  wxLIGHT_GREY
>  wxNullColour
>  wxDefaultPosition
>  WXK_TAB
>
> Quite a mess, as you can see. Recently, I have been trying to "rubify"
> all of this, but have ended up where virtually nothing in wxruby is the
> same as wxWindows for C++ or Python. I now believe that's a mistake.
>
> What if we try to stay as close to the original as possible? We would
> only change conventions when Ruby *requires* us to, such as class names
> starting with an upper-case letter. Here's the result (I think):
>
> CLASS
>  WxWindow (changed)

I think that if the class was in the module Wx you could have:

Wx::Window and yes even Wx::Object...there is no problem with using 
Object as a class inside another module.

module Wx
  class Object
  end
  class Window
  end
end

puts Wx::Window.superclass #=> 'Wx::Object'

I know you know all this...I just wanted to put it out there.  Working 
with FreeRIDE, we used to use just "import Fox" in the top of the 
files, but that littered the namespace, so now we include it in classes 
that need it instead.  This requires you to fully qualify a subclass 
relationship, but it keeps things cleaner:

include 'fox'

class MyMainWindow < Fox::FXMainWindow
  include Fox
  ...use fox constants in here with Fox:: dereferencing...
end

Realize that all you are doing is making someone type two more 
characters:

Wx::Window

- vs -

include Wx
WxWindow

I personally like the Wx::Window.

> CLASS METHOD
>  GetPosition (same)

I would use get_position

...folks will expect to see documentation that aligned with this (not 
do the translation themselves) so the docs will have to be emitted in 
this form, but my experience with working with the documentation 
(latex) files this would be pretty easy to do.

> GLOBAL METHOD
>  wxMessageBox (same)

If this is already in the module (namespace) of Wx, I don't see why you 
cannot have:

Wx.message_box

Or define another module (inside of Wx):

module Wx
  module Globals
    def self.message_box
      ...
    end
  end
end

Wx::Globals.message_box


>  EVT_MENU (same)

Wx::Globals.evt_menu

> CONSTANT, PRE-DEFINED OBJECT, PTR TO PRE-DEFINED OBJECT
>  wxSUNKEN_BORDER
>  wxLIGHT_GREY

Wx::Constants::SUNKEN_BORDER
-or-
include Wx::Constants
SUNKEN_BORDER

>  wxNullColour
>  wxDefaultPosition
>  WXK_TAB
>
> The class methods and some "global" (actually module) methods would
> start with upper case, but Ruby doesn't seem to mind that. Some

Ruby does not mind, but I believe the Ruby programmer might ;-)

> "constants" would start with lower case, but they could be implemented
> as methods that return the underlying constant, so users wouldn't try 
> to
> change the value.

I think that constants should be ALL_CAPS.  If you have class methods 
they should be
underscore_methods ... this is the Ruby way.

> The big advantage is that there is only ONE change from the existing
> wxWindows documentation. We would match not only the C++ version, but
> also wxPython. To me, that seems worth it. We can always try to figure

Again, we could write code to process the latex files and emit 
Rubyesque versions.

> out a more Rubyesque set of wrappers later, which would probably have 
> to
> include their own full set of documentation.
>
> I'll probably postpone any coding on this for a week or so, hoping to
> get more input before making more changes. I'll focus on migrating more
> classes to templates, which will make these changes slightly easier
> whenever I do them.
>
> I know I keep asking different questions, but I do appreciate any
> feedback that folks have. These questions really will set the flavor of
> wxruby for the next few years (?), so they're pretty important. You can
> probably tell that I'm not a great dictator.
>
> Thanks,
>
> Kevin

Thanks for publicly thinking through this...