API Usability

[ronyeh]

Hi MOAI team,



I'm evaluating moai for my next project, and from what I can tell, it looks really powerful. Great job! There is a decent chance we'll use MOAI going forward.



Here's my feedback for possible improvements, at the API level:

+ Consider shortening some of the class names. Rename the MOAI* prefix to M*, so that classes look like: MQuad instead of MOAIGfxQuad2D. I will be typing these names every day, and while my text editor's autocomplete is pretty good, I still usually have to Type MOAIGfx before I can trigger completion.

Here are some examples that might make my day to day life easier:

MOAIEaseType.EASE_IN => MEase.EASE_IN

MOAITouchSensor.TOUCH_DOWN => MTouch.TOUCH_DOWN

MOAIInputMgr.device.pointer:setCallback => MInputManager.pointer:setCallback

That last one is an interesting example. I found that the API seems to abbreviate some words arbitrarily, and it doesn't look very consistent (to me). But in this case, it's probably OK to expand Mgr to Manager, because once I type "MInputM" I can hit autocomplete to get the rest. With the 0.9 API, I need to type "MOAIInputM", which is 10 chars to the 7 chars in my example. The 0.9 API is thus "1.4X slower" to type. If you optimize your API's tradeoff between type-ability and memorize-ability, you could have a super slick toolkit here.



+ Provide some default initialization wrapper that makes the Hello World super short. The simplest example I could find is:

https://github.com/moai/moai-beta/blob/master/samples/basics/gfxQuad2D/main.lua

The first time I encountered MOAI, I couldn't the difference between a viewport, layer, renderpass, or prop. The Hello World could look something like:

stage = MStage.new ()

quad = MQuad2D.new ()

quad:setTexture ( "cathead.png" )

stage.addChild(quad)

In Corona SDK, the simplest hello world is two lines:

local textObject = display.newText( "Hello World!", 50, 50, nil, 24 )

textObject:setTextColor( 255,255,255 )

Having a super short Hello World is important, because it gets more people to try your SDK. The more users, the better!

My reasoning is that your API and tools are MOAI's user interface. We developers have to interact with it every day. Thus, the more streamlined it is, the better.



Thanks!

Ron



p.s. I know it's a pain in the ass to rename everything, but the MOAI prefix can be fixed with (almost) a global search/replace. I look forward to an awesome 1.0.

[anddrewscott]

I see moai as a low level API, Corona as high level. 
(I have my suspitions that moai is to corona as  chromium is to google chrome ;) )

For a high level Moai API, use https://github.com/eljeko/rapanui. It is very nice and is quite similar to Corona (addEventListener and such).

[ronyeh]

Hi Andrew,



I understand that moai is low level. I'd much prefer using moai than Corona, so it was probably a poor example for me to choose there.



But my API arguments still stand. I'd much rather have an easier-to-type API, even if I have to understand Open GL concepts (which I do).



Thanks,

Ron

[patrick]

Ron:

I'm thinking it may be possible to implement a Lua equivalent of 'using.' The idea is to iterate through the global environment and replace or remove the 'MOAI' prefix from anything that has it. Since everything in Moai is exposed through 'MOAI' prefixed class tables, this should do what you need. So:

using ( 'MOAI' )

prop = Prop.new ()

Or you could write it to replace the prefix:

using ( 'MOAI', 'M' )

prop = MProp.new ()

Re the verbosity of the API, you make a cogent argument. Point taken. That said, I don't plan to change the approach to the API. I'm really hoping that users adapt build their own high level frameworks on top of it and will have to type our object names less and less. So Andrew's comparison to Chromium is apt. It's even possible to write a Corona compatibility layer on Moai such that Corona scripts will run more or less verbatim.

But do give that 'using' workaround a shot, and if you get good results please share them. If that doesn't meet your needs, then I'll revisit options for better 'typeability' once the framework is more stable, post 1.0. 

[ibisum]

No!  Namespace is important!  This is definitely *not* more productive – there are so many M* Lua classes out there that it just doesn't make sense to open the door for namespace collisions.  Truly, you have to be a lazy programmer to want to abbreviate MOAI* to M* just because its 3 extra letters to type in – this is like having "int c;" instead of "int count;" – not a very smart suggestion, in my opinion.



(In case you're wondering, there will be instant collision with, for example, maratis3d, which has abbreviated "M*"-classes .. I've already run into collisions like this with their Engine SDK and other Lua classes written by/for lazy programmers: http://www.maratis3d.org/engine_docs/classes.html)



So, please count this as a vote *against* this idea.  OP, I urge you to reconsider your laziness.



API Verbosity: so?  Its called power.  

[gromina]

andrew said:

I see moai as a low level API, Corona as high level. 
(I have my suspitions that moai is to corona as  chromium is to google chrome ;) )

For a high level Moai API, use https://github.com/eljeko/rapanui. It is very nice and is quite similar to Corona (addEventListener and such).

Thanks for link to rapanui, It looks promising.

Agree, that current moai API forces to write too much code :(

[ronyeh]

Thanks for the feedback everyone. I would reformulate "laziness" as "a desire to be super efficient while coding my apps". So in that regard, I do consider myself a lazy (but ideally a very productive) programmer. That's why we use Lua in the first place, no? To be "lazy"?



Best,

Ron

[patrick]

Hehe. I like to think all the best programmers are also the laziest. 

[pedrocv]

I'm thinking...

Why not create a API like Corona SDK?

A good point will be that the code written in corona api will be compiled and work in moai?
The other is that the api is easy to use... there are many tutorials and an active community...

It is possible to do? Make an high level api following the corona sdk... Why not?

[sgeos]

I would reformulate "laziness" as "a desire to be super efficient while coding my apps".

If you can type, typing is not the bottleneck when programming. Thinking is the bottleneck.
think ... type ... think ... type ... think ... type ... double check ... done

[ibisum]

One thing I think about "why not to make an API" is that MOAI is already an API, and if you can use it without having to do too much in the way of weighty mounds of code to maintain something on top of what is already a decent set of interfaces to game-related mechanics, then why not do things that way?

That is not to say that I mean to think you are lazy, but definitely there is a hand-holding factor that hasn't gone on with MOAI yet.

And, after all, there are 3rd-party API's for moai already (Hanappe,moaigui,Rapanui, etc.) which have proven that MOAI's big power can be well harnessed.

Either way, have at it, and go for it if it inspires you!