Suggestion for renaming addLocal() and add() functions
I have a suggestion for renaming add() to plus() and local() functions to add(), and same goes to mult() become times() and multLocal() become mult().
what we get:
more readability.
we get to use Basic operators in some JVM languages.
what we lose:
well we got nothing to lose it’s just not easy to do it, this means that we need to change too many functions, classes, Javadoc, and the wiki.
I’ll put 2 pools:
is it better if the functions were already named as I suggested:
Yes
No
0voters
is there a chance we can do this in the near future
Yes
No
0voters
I’m aware that this topic may leed to no conclusions but can we at least try.
I agree that the alternate naming you suggest is more understandable and I have to admit I didn’t know what the ‘local’ meant for a while when I was new to the engine (much like the world “normals” - I know what it means, but I still don’t know what the root word “normal” has to do with the direction a vertex is facing )
but I imagine that it wouldn’t be ideal to change the methods altogethe and get rid of the old, otherwise we’d all need to fix 100s or 1000s of lines of code in our projects to match the new method name without any added functionality.
I suppose you could always try to use both methods - but then that would still confuse new users when they are not aware that addLocal() is not the same thing as add()
Edit:
For even better understand-ability, I think using ‘plus()’ instead of ‘add()’ and ‘plusEqual()’ in place of
‘addLocal()’ would be the best for new users to understand the method. But since I’m use to the way things are using the word ‘local,’ I’d vote to keep it that way
What about adding the proposed methods to the classes instead of replacing the existing methods? Internally they can just call the existing implementations, so the maintenance burden of this is very low. The advantage of this is that no existing code needs to change, but users of alternative JVM languages get nice overloads.
I don’t agree. Is that that complicated to understand how add vs addLocal works? I mean once you read the javadoc for one of those functions you get how it works for all the others.
As Ricardo said, your suggestion would make it a lot more confusing.
and what about divide?
There are many valid alternatives to our system, but it’s not just about naming.
A notable one is instead of having these methods in the VectorXf class would be to have a Vectors class that’s would have static methods like add(v1, v2) and add(v1, v2, store). But I doubt there is any benefit to changing it now in JME.
I don’t agree too. add and addLocal may confuse people, but once they learn the difference, they won’t probably confuse them anymore. Calling them add and plus would just confuse more because they’re synonymous.
EDIT: Credits to @RiccardoBlb, he said exactly what I said, I just realized now
To be honest, I haven’t used JME for anything yet and only played with it a bit I also haven’t looked up what the functions do (and thus how they differ)
However, with the old functions I can easily see that there is a difference in the two but if the suggested names where used I already know I’m going to switch them up. Actually, when I saw the proposed changes I got the impression that those local method names where just a quirk of the engine and acted similar to the non local ones, which going by the reactions on this thread seems to not be the case.
If however its true that using plus instead of add would make things easier at least for some people than maybe just calling add() plus() and addLocal() plusLocal() would be a good compromise?
Its probably still best to keep the old ones around at least for the time being (for obvious reasons)
Like many aspects of JME, the “Local” naming convention makes sense – once you get used to it.
Unfortunately, the convention isn’t applied consistently. For instance, there are two interpolateLocal() methods in Vector3f, but only one of them uses the old value of the vector. On the other hand, there are two slerp() methods in Quaternion, one of which does use the old value and should therefore be named slerpLocal().
I learned early on to read the source code if I had any doubt about what a library method does.
when it’s not only an addition… like addition and assignment like addLocal. People will need to read it anyway with your system since the name doesn’t make it clear of what it does.
my point was, what alternative name will you find for divide to replace divideLocal?
I meant now and in the future.
If there are inconsistencies, they need to be fixed indeed. Deprecate the old methods and create the new ones. That’s how it’s done usually in Java.
Are you talking about 8 years in the past? Did someone invent a time machine while I was on vacation?
Plus is not an operation, it’s an operator. At least by any definitions I ever heard. So it makes even less sense, at least to me (and probably others).
If we did anything at all we’d just need to replace the keyword ‘local’ with something that’s more indicative of assigning a value. Then it would be pretty much perfect.
“current add” it’s actually plus: i mean you can always say in math (0,0,1) plus (0,1,0) equals (0,1,1)
same goes for times
as for add, it makes more sense than addLocal to be for adding a value to an existing one.
divide->div
divideLocal->divide
EDIT: this is actually confusing very confusing.
so when you add 1 to 1 it’s not always 2. you are right it’s probably 10. but it’s an addition anyways.
To be clear, I don’t mean to be dismissive of your suggestion. You have a point on which most people here seem to agree, it’s that the Local word isn’t really meaningful at first glance.
To me your solution to this problem implies more, or a least, as much confusion as the current situation. However the dev cost and the backward compatibility maintenance would be quite big… To me it’s not worth it.
addLocal could have been addAndAssign… but really that makes long long lines of code.
I’ve never been fond of the Vector maths api in JME, but there isn’t much choice, since we can’t redefine operators in Java. For the best or the worst, that’s another debate
In the hope of reducing confusion, we renamed a few com.jme.math utility methods between JME 3.0 and JME 3.1 .
In hindsight, I don’t consider this a worthwhile change.
If there’s ever a major redesign (I’m thinking JME 4.0) I’d want to see these sorts of ideas on the table. Until then, I believe the core devs have better things to do.
(much like the world “normals” - I know what it means, but I still don’t know what the root word “normal” has to do with the direction a vertex is facing 
)
