Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question

3 Answers 3

up vote 24 down vote accepted

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.

share|improve this answer
2  
What if a function is known by multiple names (like foldl vs reduce, I vs id, etc?) –  hugomg Dec 12 '11 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 '11 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 '11 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. –  Jefromi Dec 12 '11 at 19:14

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).

share|improve this answer

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.

share|improve this answer
    
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 '11 at 1:18

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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