Jump to content

Last Call for API Modifications


Josh

1,904 views

 Share

I'm finalizing the Ultra App Kit API, which is going to be the basis of the new engine's API. Naming commands themselves is always a bit of an art unto itself. Some things are named a certain way because it is common convention, like Stream::Seek() instead of Stream::SetPosition() and ACos() instead of ArcCosine().

Other times we have holdovers from old APIs or BASIC syntax like Stream::EOF() or String::Mid().

Should a class that has no SetSize() method use GetSize() or Size() for a method that returns the size? I have to decide these things now and live with the repercussions for years.

Take a look through the new documentation and tell me if you have any suggestions, or forever hold your peace.

  • Like 2
 Share

8 Comments


Recommended Comments

I think that you more than anyone else know how things are going and the experience surely helps you to correct and improve things.  It's like the painter, every new work he does is a process of learning new things and correcting previous things in his paintings. 

Good luck in everything you do. 

Link to comment

I'll go through it again tonight. One thing I didn't like was that the beta had dependencies relating to VR and such included. I'm not sure if the actual project actually uses them.

Also, you're keeping the "UltraEngine" namespace for the Ultra App Kit?

Link to comment
7 minutes ago, reepblue said:

Also, you're keeping the "UltraEngine" namespace for the Ultra App Kit?

Yes. This makes it so programs that run in Ultra App Kit will all run in the full 3D engine.

Link to comment

Wasn't Stream::EOF() replaced with Stream::Ended()? Although EOF is faster to type, it conflicts with macros in some cases. 

Link to comment
4 hours ago, reepblue said:

Wasn't Stream::EOF() replaced with Stream::Ended()? Although EOF is faster to type, it conflicts with macros in some cases. 

Nothing is final. In the current build I am using EOF. It's kind of a historical name. The Win32 macro can be undefined, and I have had to do that in some other instances.

This is the great conflict. If we use more consistent naming then we have things like this:

Window::SetMousePosition()
Window::GetMousePosition()

This feels better to me, but is less easy to guess:

Window::MoveMouse()
Window::MousePosition()

The new API does have some things that feel a bit more like BASIC, like the CreateBlah() commands instead of the weird static functions in LE4.

If I am not 100% adherent to a consistent naming method than there are a lot of judgement calls to make.

Link to comment

Please don't use Window::MoveMouse! You will have users constantly asking themselves, whether that's absolute (i.e. move mouse to x, y) or relative (i.e. move mouse by dx, dy). Even if you can easily look it up I think, it is more helpful when scrolling through the autocompletion-options to just see on the first look what the function does without ambiguities.

  • Like 2
  • Thanks 1
Link to comment
On 2/6/2021 at 10:04 PM, Ma-Shell said:

Please don't use Window::MoveMouse! You will have users constantly asking themselves, whether that's absolute (i.e. move mouse to x, y) or relative (i.e. move mouse by dx, dy). Even if you can easily look it up I think, it is more helpful when scrolling through the autocompletion-options to just see on the first look what the function does without ambiguities.

On 2/6/2021 at 10:36 PM, Genebris said:

I love when everything is named like GetValue / SetValue. Clean and logical.

Thank you, that is very helpful.

 

Link to comment
Guest
Add a comment...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

×
×
  • Create New...