Download

[Improving QoL] More Consistent(Orthogonal) API

Having been using Unreal C++ API for a while, I find that the API is often inconsistent and not orthogonal.
It makes it very difficult to learn and time-consuming. If UE Reference Doc is very helpful, I’m not going to mention it here, but it’s never been helpful. It is wastes of my searching time.

Oh well, I’m not sure where to begin but I wish you can fix the API that is the most commonly used first.
For example, Actor and Component.

  1. Actor->GetActorTransform() vs Component->GetComponentTransform(). Why not just *->GetTransform()? Having explicit Actor or Component have any special meaning?
  2. If you meant to get World Transform, call it GetWorldTransform() instead of implicit Get*Transform(). This way having GetRelativeTransform() makes more sense.
  3. World* and Absolute* are inter mixed. Inconsistencies make it difficult to use API
  4. AddWorldOffset instead of AddWorldTranslation. Why offset all of sudden?
  5. Use GetParent() instead of meaningless GetAttachParent(). Is there non-attach parent too?

These are just the tip of the iceberg. Even the most common C++ API is really horrible.
I have to look it up every time and curse.
There doesn’t seem like any consistency at all. Probably because it was written by several people??
Will you then please fix it? Luckily we have UE5 coming up. If it’s doesn’t get fixed in UE5, it will never be fixed for the next decade or more.

Please have API Design Review Meeting before UE5 becomes final and fix them once for all.

What I think a good API is that naming needs to be consistent. No one will argue with that.
And there is one other important aspect people don’t talk about. It also needs to be Orthogonal. For example, if there is GetName() for one class, I expect there is GetName() for other classes that have a name, regardless it’s used often or not. Likewise, if there is a parent, I expect there is GetParent() and GetChildren(), and etc, if there is transform built-in, I expect the full set of Transform API available directly on the class through consistent naming. This is what I mean by Orthogonality. With that in mind, I wish you go back and add the missing API to commonly used classes. Having more APIs(Orthogonal) is better than having no APIs.

My two cents,

Thanks.

Just to add two more examples which are super-generic and really annoying imo:

  • Position vs Location
  • Mouse vs Cursor (GetCursorLocation? GetMousePosition?)
1 Like

Yeah, I agree. Position and Location are often intermixed,
I usually distinguish them by having my own rule.

Location means just Translation.
Position means it has both Translation and Rotation. Translation + Rotation is often used together it’s very convenient to have them a special name.

Likewise, I try to make distinctions of the followings,

Get* : always returns something valid. (no need to check validity)
Find* : may return null. (need to have a validity check)
Search* : takes quite more time than Find. (use with care)

Having these rules makes it easier when I have to name things and remember things even if it’s just for me.

UE API is being used by thousands of people and they should really design it very carefully as it will affect many people every day and for years to come.