Haskell platform proposal: split package - concerns about synonyms in API

[Ben Moseley]

Firstly, I agree that adding splitting functionality to Platform would be very useful - so thanks for all the work you've done.

On the naming side of things, I'd just like to say I agree with Roman here - I think having synonyms in an API is a bad idea. (It's one of the things I've disliked most about Coq).

I think there might be an argument that synonyms improve things for those who know the API really well - but that comes at the cost of worsening the experience for those (i.e. most) who know it moderately or fairly well and thus - when reading code written by others - find themselves struggling to remember whether the variants that they don't use personally are subtly different or not.

Anyway, I'd be strongly in favour of removing the synonyms (or at least side-lining them into a separate not-exported-by-default module) before adding to the platform.

--Ben
P.S. I think "intercalate" is an awful name, and "unintercalate" is certainly no better ;-) - so I'd be in favour of choosing one of the other two.

On 22 Jul 2012, at 01:43, Brent Yorgey wrote:

> On Sat, Jul 21, 2012 at 11:40:19PM +0300, Roman Cheplyaka wrote:
>> * Brent Yorgey <byorgey at seas.upenn.edu> [2012-07-21 08:09:09-0400]
>>> On Sat, Jul 21, 2012 at 09:24:16AM +0300, Roman Cheplyaka wrote:
>>>> 
>>>> Regarding the API: I'm a bit concerned with presence of synonyms there
>>>> (e.g. chunk = splitEvery, sepBy = splitOn etc.) IMO it makes it harder
>>>> to learn the API (which is not small even without the synonyms), and
>>>> especially to read other people's code if their preferences in naming
>>>> differ from yours.
>>> 
>>> Would your concern be addressed by Gábor's suggestion to group
>>> synonyms together in the documentation?
>> 
>> This could be a minor improvement (I haven't checked how these
>> grouped functions look like in haddock), but I don't see the need for
>> synonyms in the first place. Could you maybe explain the motivation
>> behind them?
> 
> Certainly.  The idea is to provide synonyms whenever there are
> multiple common names in use, as well as a consistent system of names
> within the package itself.  The goal is for new users to be able to
> get started using the library as quickly as possible -- users will
> usually come looking for some particular function and they may already
> have an idea about what it might be called.
> 
> To be concrete, the split package has three sets of synonyms:
> 
>  * splitOn / sepBy / unintercalate
> 
>    Here 'splitOn' is an internally consistent name, which matches
>    with the naming scheme used in the rest of the package.  'sepBy'
>    is a name from parsec and other parser combinator libraries;
>    'unintercalate' emphasizes that this function is right inverse to
>    'intercalate'.
> 
>  * splitOneOf / sepByOneOf
> 
>  * splitEvery / chunk
> 
>    Again, 'splitEvery' matches the internal naming scheme; 'chunk' is
>    a name commonly used for this function within the community.
> 
> I don't see much harm in this (modulo making the documentation
> clearer, which I plan to do).  And I really don't want to *remove*
> existing names because that would force a major version bump and
> potentially break any code depending on split.
> 
> -Brent
> 
> _______________________________________________
> Libraries mailing list
> Libraries at haskell.org
> http://www.haskell.org/mailman/listinfo/libraries