Naming conventions for functions in similar modules

[Jose Armando Garcia]

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.

Thanks,
-Jose