API naming inconsistencies

I know there’s probably way too much water under the bridge for this to ever change, but one thing that has really bugged me about the API is the lack of consistency in some naming conventions. The most obvious example being the plethora of “InPlace” operations found in the Vector classes.

For example:

.multiply() - does not modify the vector, but returns the result in a new Vector3.
.multiplyInPlace() - modifies the value of the vector.


.normalize() - modifies the value of the vector.
.normalizeToNew() - does not modify the vector, but returns the result in a new Vector3

This is just one of many examples that I’ve found. Why do we have “in-place” methods at all? Wouldn’t it make more sense to have methods always operate on the object itself, and save static functions for creating new objects? Like so:

Vector3.prototype.multiply(v) - Modify vector “in place” by v, returning nothing.
Vector3.Multiply(v1, v2) - Return result of v1 * v2 in a new Vector3.

… and just keep this theme consistent across all objects? The way it is now is very confusing, extremely difficult to remember, and clutters the API.

Like I said, probably way too late to do anything about it at this point, but maybe for future reference? I know it’s extremely difficult when you have so many different people contributing, but I think enforcing some consistent standard here would really help keep things cleaner going forward.

Yeah, a bit of history, a lot of contributors, me being stupid and you get the math API :slight_smile:

Anyway, as you mentioned it is too late to change it. But we can surely make sure (and we do) to work on better naming for new APIs

For instance the toRef is now pretty well spread across the math API. Initially, a.multiply(b) was designed that way to mimic the operator like a * b, instead of relying on Vector3.Multiply(ab, b) which seemed less obvious (at least to me) at that time.

My biggest concern is normalize() as it must have been named normalizeInPlace.

1 Like

we will survive this :smiley:


We could probably add function aliases to increase API consistency while maintaining backwards compatibility.