1 hour ago, Hodgman said:

I guess it depends what your naming convention for variables is. If you're using some horrible systems hungarian where you attach the data type to the variable name, then sure, you'd have something redundant like:

GetAnimByName( pszMyAnimation1 ); // slow string-based logic
GetAnimByIndex( uidxMyAnimation2 ); // fast index-based logic

But if your variable is just called "myAnimationN", then the call-site could look like:

GetAnim( myAnimation );//is this the fast path or the slow path?

 

You will almost always have context around that line of code to tell you what the variable is, even if the variable isnt named in a descriptive manner.   The problem with your example isnt the "GetAnim()" part, it's the fact that the variable is named "myAnimation".  Looking at "myAnimation" I'd expect I'm looking at an instance of an Animation object, or perhaps a reference (or pointer) to one.  I would not expect to be looking at either an animation name, or animation path, or animation index.  But then again I like to give variables appropriate names.

Again, it seems that the blame is being put on the wrong things here.  Overriding GetAnim() to take an index and a name seems like a perfectly sensible thing to do.   It's a descriptive and unambiguous function name.  Saying that it's problematic because the programmer gives variables ambiguous names seems to totally miss the real issue.   

13 minutes ago, 0r0d said:

Again, it seems that the blame is being put on the wrong things here.  Overriding GetAnim() to take an index and a name seems like a perfectly sensible thing to do.   It's a descriptive and unambiguous function name.  Saying that it's problematic because the programmer gives variables ambiguous names seems to totally miss the real issue.   

I'm pretty sure this is a subjective / style choice, not an objective truth

Ambiguous function names vs ambiguous variable names. Take your pick! If one seems more sensible, that's a stylistic choice, hopefully with some reasoning, but also with some gut feeling. 

My argument as to the function name being ambiguous is that, from a performance point of view, they're extremely different functions. One is a very expensive *search* operation on variable length keys, the other is a zero-cost array indexing operation. Very different things - misleading and outright dangerous to pretend they're at all similar in any way.

A high level gameplay programmer might also argue that they're semantically identical - no difference at all! They're both just key/value lookups for an object with two keys. Of course they should be named the same.

You can understand an argument without having to agree with it

If this was deep inside the engine, I would give more weight to the first argument. If this was being bound to Lua scripted gameplay code, I would give more weight to the second argument. Sometimes code styles are only appropriate within certain problem domains.

8 minutes ago, Hodgman said:

 

My argument as to the function name being ambiguous is that, from a performance point of view, they're extremely different functions. One is a very expensive *search* operation on variable length keys, the other is a zero-cost array indexing operation. Very different things - misleading and outright dangerous to pretend they're at all similar in any way.

Are you saying the two functions are not similar in any way??

Ok, so you're arguing that the functions are ambiguous, but like I said it's usually the case that you know exactly what's being passed into that function.  Maybe not in something like LUA, but in typical c++ code you will know.  (one reason why I try to keep the use of auto to a minimum)   And you will certainly know if you're writing the code to begin with, since you must have looked at the header and seen the function prototypes.

In any case, you're arguing a specific case and the OP was asking a general question.  

"why function overloading must be avoided in most cases"

In most cases, if you have functions that do the same thing and are only different in what single parameter they take in, I'd say that naming them the same is a perfectly valid thing to do.  Yes, it's a matter or preference, but really only that.

I'm against overloading.

Sticking with a single fundamental access type and using external converters leaves the class definition untouched/stable.

const anim* get_anim( const int &index ) const;

get_anim( std::stoi( "4" ) );

std::map< std::string, int > anim_name;

get_anim( anim_name[ "wobble" ] );
  
// maybe...
get_anim( button.get_index() );

// returns the animation with the given index, or nullptr if the index is invalid
const Anim* TryAndGetAnim(const int index) const;

// returns the index associated with the name, or -1 if it fails to find it
int FindAnimIndex(const char* name) const;

Now you can get the same functionality, but the function isn't repeated twice. No overloading necessary. The "finding index" and "getting the animation" concepts are now in separate functions and can be used in other places as separate things.

I am not opposed to overloading, but I don't think this is the best use case for it.

14 minutes ago, Oberon_Command said:

// returns the animation with the given index, or nullptr if the index is invalid
const Anim* TryAndGetAnim(const int index) const;

// returns the index associated with the name, or -1 if it fails to find it
int FindAnimIndex(const char* name) const;

Now you can get the same functionality, but the function isn't repeated twice. No overloading necessary. The "finding index" and "getting the animation" concepts are now in separate functions and can be used in other places as separate things.

I am not opposed to overloading, but I don't think this is the best use case for it.

I find the "Try" a bit ambiguous since the name is also associated with try/catch clauses. "GetAnim" should suffice, for the remainder (i.e. what happens if the index does not match anything?), you should read the specifications of the method, IMHO.

Furthermore, it could be beneficial to have multiple ways of accessing the "Anim" with regard of performance (I am not saying they should all have the same name). Of course: make it work -> make it right (refactoring) -> make it fast (profiling/optimization); so alternative ways (if beneficial) should only be added in the end.

1 hour ago, matt77hias said:

I find the "Try" a bit ambiguous since the name is also associated with try/catch clauses. "GetAnim" should suffice, for the remainder (i.e. what happens if the index does not match anything?), you should read the specifications of the method, IMHO.

I disagree. try/catch has a sufficiently visually different syntax from a function invocation that I would hope nobody would ever mistake the two.

The implication of the "try" function nomenclature is that the function could fail in a recoverable way, or in a way that allows you to have different behaviour when it fails. Some would argue that exceptions are preferable here; not all of us use exceptions or even think that exceptions in C++ are a good idea. The explicit naming is useful when we want to obviously distinguish between functions that can fail and functions that cannot - eg. in the case where, for performance reasons, you want to access an animation by index without bounds checking. That difference is an important aspect of the functions' semantics.

// returns the animation with the given index, or nullptr if the index is invalid
const Anim* TryAndGetAnim(const int index) const;

// returns the animation with the given index - asserts if the index is invalid,
// this function should never be called when we don't already know that the index is valid
const Anim& GetAnim(const int index) const;

// returns the index associated with the name, or -1 if it fails to find it
int FindAnimIndex(const char* name) const;

// use cases:
if (const Anim* anim = TryAndGetAnim(FindAnimIndex("run")))
{
  //...
}

int animIndex = FindAnimIndex("run");
if (animIndex != -1)
{
  // use the index here...
  const Anim& anim = GetAnim(animIndex);
  // ...
}

Having the different name also lets you avoid the fact that you can't overload functions by return type alone, of course.

Quote

Furthermore, it could be beneficial to have multiple ways of accessing the "Anim" with regard of performance (I am not saying they should all have the same name). Of course: make it work -> make it right (refactoring) -> make it fast (profiling/optimization); so alternative ways (if beneficial) should only be added in the end.

I don't see any functional difference between GetAnim(FindAnimIndex("run")) and GetAnim("run"). The performance difference is likely meaningless, depending on how these are used, and I'd argue that the first one is much clearer than the second one even if it's more verbose. I want to be able to tell at a glance whether a search algorithm is happening or whether a simple indexed lookup is happening. Chances are good my peer reviewers (you do have a peer review process on code checkins, right?) are going to want the same thing.

Of course, one could also invert the above paradigm and change the names a bit:

// returns the animation with the given name, or nullptr if we didn't find it
const Anim* TryAndFindAnim(const char* name) const;

// returns the animation with the given name - asserts if we didn't find it,
// this function should never be called when we don't already know that the animation exists
const Anim& FindAnim(const char* name) const;

// returns the index of the animation, or -1 if it isn't in this container or is nullptr
int ComputeAnimIndex(const Anim* anim) const;

As you suggest, you could have both. In that case having different names is an absolute must; note that in my second code example I'm using "Find" rather than "Get." This is because to me "Find" implies a search operation (probably one that's O(n)) while "Get" implies a simple O(1) lookup.  Furthermore, as you suggested, I probably wouldn't write the extra functions up front, I'd wait until a need for them was demonstrated. I'd write whichever set of functions was the most common case at the time I needed the functionality.

Ultimately, this still isn't a good use case for overloading. Overloading should be used in cases where there is no semantic difference between the functions and the only difference is the types they take, as with trig functions taking floats or doubles.

16 hours ago, Oberon_Command said:

Ultimately, this still isn't a good use case for overloading. Overloading should be used in cases where there is no semantic difference between the functions and the only difference is the types they take, as with trig functions taking floats or doubles.

More specifically, a difference in types that must be dealt with by the function, not by the caller. If the caller can convert would-be function parameters to equivalent values of other types only the "standard" parameter type should be supported.

Mathematical functions are an appropriate example: float and double computations of the "same" function are implemented differently and have different results.

On the other hand there's no reason to add complication to provide overloads over float-precision complex numbers represented as std::complex<float> or std::tuple<float,float> or std::pair<float,float> or std::array<float,2> or two floats, as these representations can all be converted trivially and exactly to each other.

The whole point of frameworks is so whoever is using it has less work to do. Nobody wants to learn a million tediously different functions if they do the exact same thing but are called with different parameters. There are a million ways to do the same thing, no right answer obviously, so just use your best judgement when doing things like overloading. If two functions are named the same, and do completely different things, maybe make the name a little more descriptive. 

I think the example in the OP was only a good example of a bad use of overloading, but not a great argument for why overloading in general is a bad idea.

I don't mind the "Try" function naming, but i'd prefer it to return a boolean, and have an out parameter for the return anim, basically like how TryParse works in .net

1 hour ago, iedoc said:

I don't mind the "Try" function naming, but i'd prefer it to return a boolean, and have an out parameter for the return anim, basically like how TryParse works in .net

We're getting a bit off topic, but the advantage of the "Try" functions returning a pointer is that you can restrict the scope of the local variable used to store the function's return value to the if block used to test for the function's success. It also allows the return value to be used ONLY for validity testing (eg. when I only need to know that something exists, not to actually use it, which is useful in some cases) without having a spurious dummy variable the way the .Net "TryParse" style does.

// repeated from my post above...
// note that we can't accidentally use anim outside this block where it might be nullptr!
if (const Anim* anim = TryAndGetAnim(FindAnimIndex("run")))
{
  //...
}

// in C++'17 with non-integer types we could use an optional type
if (const std::optional<int> animIndex = TryAndFindAnimIndex("run")) 
{
  // ...
}

// we could also do this with types that don't evaluate to booleans, without optionals
if (const int animIndex = FindAnimIndex("run"); animIndex != -1) 
{
  // ...
}

// and I guess the TryParse way, too, but without this syntax, 
// if we don't need the value, or we don't have a sensible default value, that way could result in bugs...
if (const Anim* anim = nullptr; TryAndGetAnim(FindAnimIndex("run"), &anim))
{
  // ...
}