Inconsistencies in function names

[eksperimental]

I have reviewed some time ago the function names in the whole of the
Elixir project, and I have found a few inconsistencies. Some days ago
this issue was brought up by me in a new function that was just named
( https://github.com/elixir-lang/elixir/pull/3464 ), so here I am with
the list.
While I am aware that most of them have been inherited from the names
of Erlang functions (and even Haskell and Unix), I think we should be as
consistent as possible when naming them.

* Whenever you see indented functions, it's a function in Elixir with a
similar name, so it's easier to compare.

** This list is 3 months old, so any new function introduced during this
period is not included.

*************
Inspect.Algebra.folddoc/2
Code.get_docs/2
Inspect.Algebra.to_doc/2
Module.add_doc/6
Proposed: Inspect.Algebra.fold_doc/2

Process.whereis
Proposed: Process.where_is

Enum.minmax
Proposed: Enum.min_max

Enum.minmax_by
Proposed: Enum.min_max_by

###
# These List.fold* come from Haskell, but it is weird to have l & r as
# left and right, as I haven't seen in it in other function names,
# such a short name
List.foldl/3
File.cp_r/3
File.rm_rf/1
File.ln_s/2
Proposed: List.fold_left/3 or List.fold_l/3

List.foldr/3
File.cp_r/3
File.rm_rf/1
File.ln_s/2
Proposed: List.fold_right/3 or List.fold_r/3

###
# And these ones come from their Erlang counterpart.
List.key*

List.keyfind/4
Enum.find/3
Enum.find_index/2
Enum.find_value/3
System.find_executable/1
Task.find/2
Proposed: List.find_key/4 or List.Key.delete

List.keydelete/3
Application.delete_env/3
Code.delete_path/1
Keyword.delete_first/2
List.delete_at/2
Module.delete_attribute/2
Process.delete/1
Supervisor.delete_child/2
System.delete_env/1
Tuple.delete_at/2
...
Process.get_keys/1
Dict.has_key?/2
Proposed: List.delete_key/3 or List.Key.delete/3

List.keyreplace : List.replace_key or List.Key.replace
List.keysort : List.sort_key or List.Key.sort
List.keystore : List.store_key or List.Key.store
List.keymember? : List.key_member? or List.Key.member?

###
# Here all the Path.*name functions,
# I can see this come from Unix/Linux functions, but only "basename"
# and "dirname" are, the rest just come from asimilating the naming
# convention
Path.absname/1 : Path.abs_name/1
Path.absname/2 : Path.abs_name/2
Path.basename/1 : Path.base_name/1
Path.basename/2 : Path.base_name/2
Path.dirname/1 : Path.dir_name/1
Path.extname/1 : Path.ext_name/1
Path.rootname/1 : Path.root_name/1
***********

[Booker Bense]

I have to ask "Is the game worth the lantern?" 

(i.e. is breaking existing code and the required version/documentation update worth the added value of consistency?) 

My opinion is that the it's far too late to impose any consistency requirements on existing API's. 

It's certainly fine to look at consistency going forward, but once an API hits version 1.0, I think

you have to have a very significant reason to change it. 

See http://semver.org

These would be Elixir 2.0 changes in my opinion and frankly I'd be really pissed to make patches 

based on a foolish consistency. These are the kind of changes that you need to look long before

verison 1.0 

- Booker C. Bense

[Peter Hamilton]

There is also the option of aliasing rather than breaking the api.

To me the usability problem is when you assume consistency and get bit by it.

I'd support adding aliases immediately if we're confident it will improve usability.

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/70cf1067-e8d1-4ba8-bd86-eb030c6c7fe8%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Robert Virding]

This is a major problem we ran into with the erlang libraries. After the language/system has started to be used it is extremely difficult to make backward incompatible changes. You basically have to live with your mistakes. :-) You can define new modules but it feels a bit strange to have a module Foo then fix it in a NewFoo. You do need to define a procedure for making such changes but you need to give users plenty of time to migrate.

Robert

[Bruno Matos Tavares]

My 5cents:

Alias sounds as a good solution as implementation wise nothing changes (not even overhead). On the official documentation should show deprecated, reason, link to the new signature and estimate removal version (e.g. V1.2). I don't see a reason why shouldn't be done.

[Robert Virding]

One problem with alias is that it can make error message confusing. What you see is not what you get.

Robert

[Bruno Matos Tavares]

Good point but defdelegate is used quite a bit. E.g. defdelegate [keys(map), values(map), size(map), merge(map1, map2), to_list(map)], to: :maps

I believe consistency should prevale specially because Elixir is quite young.

Bruno.

[Steve Domin]

Agree with Bruno's point, Elixir is quite young and it's still time to make it consistent.

[eksperimental]

I also agree with Bruno and Steve,
Elixir is still very young, so the sooner we fix these issues, I think
the less traumatic it will be in the future. But I also understand
that adhering to the rules that Elixir chose to stick to is important
(http://semver.org)
Besides whatever decision is taken regarding this issue, I think we
should maintain a list of the Inconsistencies that we currently have in
the language, and keep track of the ones we had in the past and had
been corrected. A document that newcomers to the language can read and
know beforehand when things don't work as expected, and also a document
that developers can look at and learn what mistakes not to make in the
future. (I'm happy to voluteer on this one).

Enum.mixmax*
------------
Regarding the functions that I mentioned in my list, I think we can get
away with renaming `Enum.minmax` and `Enum.minmax_by` since they have
been introduced to v1.1.0-dev (the thing is that is has been introduced
almost 7 months ago, https://github.com/elixir-lang/elixir/pull/2901),
should we hard-deprecate it, or simply rename it? Only 1 file in all
the github repos is using (Enum.minmax), and that's the person who
contributed this function
*
https://github.com/search?utf8=%E2%9C%93&q=minmax_by+language%3AElixir&type=Code&ref=searchresults
and nobody is using Enum.mimax_by
*
https://github.com/search?utf8=%E2%9C%93&q=minmax_by+language%3AElixir&type=Code&ref=searchresults


Algebra.Inspect.folddoc
-----------------------
A similar situation happens with this function, the only difference is
that this function has been introduced in v1.0
but only two repositories are using it in github
https://github.com/search?utf8=%E2%9C%93&q=folddoc+language%3AElixir&type=Code&ref=searchresults
one of them being the contributor of the function (probably the code
that ended up in elixir)
( https://github.com/search?utf8=%E2%9C%93&q=folddoc+language%3AElixir&type=Code&ref=searchresults
)

[José Valim]

Please send a PR that simply renames both. We can just rename min_max because it was not released. I will add a deprecation in the compiler for folddoc though.

José Valim

www.plataformatec.com.br

Skype: jv.ptec

Founder and Director of R&D

--
You received this message because you are subscribed to the Google Groups "elixir-lang-core" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elixir-lang-co...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/elixir-lang-core/20150717162303.2969a6ed.eksperimental%40autistici.org.

[eksperimental]

Would it be possible to create an option in `alias` and `defdelegate`
macros to keep track of the original Module.function invoked, so we
could pass it around, and keep track of what was the original function
beind called.

I have no idea how difficult this would be to implement. I'm just
thinking that it will make life much easier when it comes to situations
like the one we are facing.