4

I'm designing a small library and there is a strong temptation to provide synonyms to some of the exported functions.

var foldl = function(){ ... };
var reduce = foldl; //reduce is a synonym for foldl

I imagine that the multiple names might help the initial learnability of the API (since the user is more likely to stumble on the function he wants) but at the same time I worry the duplication will bring needless complexity.

What rules should I keep in mind when thinking about adding a synonym to a function in my API?

When whould I choose a "there is more then one way to do it" api and when should I incentivize there is one way to do it" instead?

Improve this question

3 Answers 3

Reset to default
25

Don't provide multiple ways to do the same thing - that will just confuse the API users.

Having several names for the same things means you don't have a good name for it.

Improve this answer
4
  • 2
    What if a function is known by multiple names (like foldl vs reduce, I vs id, etc?)
    – hugomg
    Dec 12, 2011 at 16:03
  • 3
    @missingno - Use the most well know and in your documentation (you do have documentation, right?) explain that these names map to this function.
    – Oded
    Dec 12, 2011 at 16:04
  • 5
    @missingno: Pick the one most appropriate for your users. If your users are likely to know haskell, use foldl. If they know python, use reduce, and so on.
    – Daenyth
    Dec 12, 2011 at 16:17
  • 2
    Having several names also means potential maintenance headaches for you later, and huge readability problems for users of your library; they'll all end up having to know multiple names for everything if they look at others' code.
    – Cascabel
    Dec 12, 2011 at 19:14
2

Not only is it confusing to use multiple names for the same thing, but this will also pollute the namespace of whoever is using your API. In c# i am often tortured by not being able to name my variables default or checked =P. Knowing a bit of Perl, my intuition is also that functions which seems like they do the same thing are usually subtly different (chop, chomp).

Improve this answer
1

Just use one. The only situation I can think of where you may want both is if there are two separate business domains that just happen to require the same function at this time, but they could split later. I know that's YAGNI, but if they are 'considering' it at this time, you may want to think about it.

Improve this answer
1
  • Not sure this makes splitting simpler. People will use it wrongly. So every instance has to be checked on such a split.
    – johannes
    Dec 13, 2011 at 1:18

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.