Re: Haskell platform proposal: split package

Hi, not sure if that adds anything to the discussion, but I share Roman's concerns. On Sat, Jul 21, 2012 at 08:43:05PM -0400, Brent Yorgey wrote:

On Sat, Jul 21, 2012 at 11:40:19PM +0300, Roman Cheplyaka wrote:

...

* Brent Yorgey [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.

This was at least not true for me. When I first looked at split, I was utterly confused about all those synonyms. This was one of two reasons why I decided not to use it (having an other dependency was the other).

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

Making the documentation clearer would mitigate Roman's first concern (learning the API). But it would not address the second concern (reading/understanding other peoples code), which to me is even more important.

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.

I think this particular point can be addressed by either deprecating synonyms; or by removing the Haddock comment from synonyms and use: {-# OPTIONS_HADDOCK prune #-} That way the synonyms do not show up in documentation, but are still exported. Cheers, Simon