Jump to content

Last Call for API Modifications


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

8 Comments


Recommended Comments

Yue

Posted

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. 

reepblue

Posted

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?

Josh

Posted

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.

reepblue

Posted

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

Josh

Posted

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.

Ma-Shell

Posted

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
Genebris

Posted

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

  • Like 3
  • Thanks 1
Josh

Posted

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.

 

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...