Yeah, I can understand that base point. However...
I only understood that based on context from previous APIs that have been implemented in similar ways. If I created a new language, and showed you a code snippet from it that looked like this "
for (i = 0; i < users.getLength(); i += 1)" you would understand what that means in a heartbeet, because we've all had to learn how these C-style for loops work. But, that doesn't mean it's good design. If you stop to think about it, the syntax for that for loop is actually quite odd - thank goodness many newer languages are simply not including a for-loop that looks like that.
Similarly, many previous APIs like to simply return booleans or numbers without context, but that doesn't mean it was a great design decision. I could only understand what
if (mySet.add(element)) would do based on context I've had with past experience with other array/set/map API's I've worked with. Newer programmers don't have this kind of context, so knowing what that
"if" will do is tricker for them.
What's more, something like
if(set.multiAdd(x, y)) would be a lot more ambiguous to me. I would expect multiAdd() to return a boolean, based on the context I see it in, and based on other APIs I've worked with, I would expect it to be a boolean indicating success status. So, what if "x" was successful and "y" was not? Would it be true or false? I wouldn't know, until I look at the docs and saw that it in fact returns a number. Something like
if(set.multiAdd(x, y).successCount) would have been much clearer to me.
Edit: With all of this said, I was mostly talking about a general principle of self-documenting what return values are. I think this is more important for some APIs than others - The general idea of
if(set.multiAdd(x, y)) is still somewhat understandable, even if the specifics are not. Something like
return createUser('sally') would be much worse if that return value was a temporary password that was assigned to the new user. No one would guess that in a million years - It would be much better if a little more context were provided, like this
This is a very good point.