Naming conventions for functions in similar modules

[Jonathan M Davis]

On 2011-06-21 22:31, Jose Armando Garcia wrote:
> On Wed, Jun 22, 2011 at 2:15 AM, Jonathan M Davis <jmdavisProg at gmx.com> 
wrote:
> > Okay. In discussing a pull request which involves reworking std.ctype
> > (which is going to be changed to std.ascii) and std.uni, a naming issue
> > has arisen which really needs to be decided on. It's going to affect
> > other modules in the future (particularly std.algorithm and
> > std.parallel_algorithm), and we need to decide how we're going handle it
> > in general.
> > 
> > Let's say you have two modules which do essentially the same thing but do
> > it differently (such as std.ascii operating on ASCII characters and
> > std.uni operating on unicode characters or std.algorithm operating
> > serially and std.parallel_algorithm operating in parallel). Should the
> > functions in those two modules be named identically, or should they have
> > something in their name to distinguish them. For example, should we have
> > std.ascii.toLower and std.uni.toLower or std.ascii.toAsciiLower and
> > std.uni.toUniLower? Or in the case of std.*algorithm, std.algorithm.sort
> > and std.parallel_algorithm.sort or std.algorithm.sort and
> > std.parallel_algorithm.pSort?
> > 
> > If the functions are named differently, it will be clear at a glance
> > which of the two modules they're from, and there will never be any name
> > clashes, but the names are going to tend to get longer and uglier. You
> > also lose the ability to swap out one module for the other and have your
> > code just work.
> > 
> > If the functions are named identically, then you  _can_ swap out modules
> > and have the code just work, but it's not immediately clear which module
> > a function is from until you look at the imports. You also have to deal
> > with name clashes when importing both modules. However, D's import
> > system deals with that by forcing you to either give their full path or
> > alias them. So, there's no hijacking going on, and since you can alias
> > the functions, that means that you can use distinct names for them in
> > your code if you want to even if Phobos doesn't.
> > 
> > So, the question is, which scheme do we go with in Phobos? Both have
> > their pros and cons.
> > 
> > Because going for different function names is going to mean that
> > functions are going to end up with longer, uglier names, I find that
> > going for different names is a bit distateful, but it _does_ have the
> > advantage of making it immediately obvious which version of a function
> > you're calling. However, what I find particularly disturbing about
> > taking that route is that it implies that the D import/module system
> > can't do its job, since we feel the need to add stuff to function names
> > just to avoid name clashes, when the import/module system is set up
> > specifically so that it will handle such clashes cleanly and avoid
> > function hijacking. So, I'm leaning towards having the function names,
> > be identical between modules, but it's definitely debatable.
> > 
> > So, we need to make a decision on this. Thoughts? Opinions? Which of the
> > two naming schemes should we go with in Phobos?
> > 
> > - Jonathan M Davis
> 
> It is a matter of scalability. Having to look, know, take into
> consideration other modules that are independent of your module when
> coming with meaningful name doesn't scale. A module should only be
> concerned with itself and its dependencies. Imagine a library 100
> times the current size. Having to consider all the other modules when
> coming up with name is not reasonable.
> 
> That doesn't mean that there should be consistency between the modules.
> 
> In other words. I think the name should be lower and not toLower and
> toUniLower. Why not toLower? To me to... implies conversion hence
> std.conv.to and toString. Why not toUniLower? It is define in std.uni
> so of course you mean unicode.

To be clear. This is not intended to be debate about what exactly to name a 
particular function. The question is the general naming scheme with regards to 
modules which are very similar and have many of the same functions. Should the 
names between them be identical when the functions do the same thing, or 
should something be added to their names to make them distinct from one 
another?

You do seem to be arguing for naming them the same, so that's good feedback, 
but the issue of toLower vs lower is irrelevant to the goal of this 
discussion.

- Jonathan M Davis