stdlib naming inconsistencies

[subsetpark]

The standard lib has a couple different naming conventions that conflict with each other.

For instance, the stdlib has functions for two common operations on sequences: sorting and reversing. Each one has an effectful and a non-effectful variant, which mutate the existing data structure or return a new one respectively. However, they abide by different conventions to communicate this.

For reversing a sequence, the effectful variant is reverse! and the functional one is reverse, using the common lisp convention of ! to indicate an effectful function.

On the other hand, sorting uses sort and sorted respectively, following a convention most familiar to me in Python.

I personally think the former convention is a little nicer and more productive, but arguably having a consistent naming scheme in either direction would be a step forward.

Since this is a breaking change, we could introduce sort! as a synonym for sort without necessarily removing sort. We couldn't make a non-breaking change in the other direction, introducing reversed, because the presence of reversed would imply that reverse had effectful semantics.

[uvtc]

Janet already has a number of functions that mutate their args and which do not end with a!: put, set, update, array/push, array/insert, array/remove.

Personally, I like the ! convention. And I really like consistency.

Also, a question: should the side-effecting variant (either sort! or sorted, reverse! or reversed) return anything? If we know they're modifying their arg, why return anything? I notice that the docs for (the currently-side-effecting) sort don't mention it, but it indeed returns the sorted array --- just like how reverse! currently returns the reversed array. Why do sort and reverse! do this?

Two final cents: as a Janet user, I'm happy with breaking changes that improve consistency.

[subsetpark]

I think the usefulness of returning the ds in the case of mutating functions is that they can be used more easily in pipelines and the like. It's nice to be able to structure your code as a simple composition of functions, even if you're reusing the same data structure as an implementation detail.

[andrewchambers]

I wondered if map and filter should really be called 'mapped' and 'filtered', however this breaks convention with other languages. I think perfection is kind of unattainable sometimes due to the imperfect nature of humans :P. The software systems we build don't care about minor inconsistencies, but do rely on backwards compatibility haha.

I don't even know if there is a rule for when something should be describing what the function returns, vs describing what a function does. I kind of feel it's to do with side effects? not really sure.

[bakpakin]

Yeah, hindsight is 20/20 when naming things. I don't think it is a huge issue, and as for breaking changes, everyone is happy with breaking changes that don't break their code. I thing the problem with adopting the ! suffix is that so many functions in the core mutate inputs that it would just become extra noise in the code. It works in Clojure because most functions don't mutate inputs.

Anyways, what I will not do is append ! to all functions that mutate their input for the sake of bike shedding.

[andrewchambers]

another one is sort-by should perhaps be sorted-by.

edit: this was actually a doc bug.

[subsetpark]

@bakpakin - another non-breaking change you can make in this direction is introduce reversed as a synonym for reverse. That would be another way to establish a consistent pattern without removing or renaming any functions (and without leaning too heavily on !, as you’ve indicated)

[uvtc]

@subsetpark , so, given current behavior, you're suggesting:

• side-effecty: reverse!
• returns a new one: reverse ( <-- make reversed a synonym for this one)

But then at some point down the road it would still be desirable to change the name reverse! to reverse, causing the breaking change.

How do other languages deal with breaking changes like this?

[subsetpark]

Lots of languages these days have nice deprecation mechanisms: you can tag them or wrap them in a macro which will print at compile time when the deprecated function is invoked.

[uvtc]

(Posted this to gitter, but more relevant here.) I'm guessing that I'm missing something important here, but I have an idea that may be poor design and hopefully someone can tell me why that's so. :)

If both sort and sorted return an updated object, the only real difference between them is that sort returns the same object but sorted returns a new sorted copy. Since this is the case, why not only have one function, sort, that by-default mutates its arg, but if you pass some particular option/flag, it leaves the arg alone and returns a fresh (and sorted) copy?

That way you no longer need two names for it.

[subsetpark]

I think the best answer is something along the lines of: the semantics of mutation is a sufficiently dramatic distinction that it feels odd and potentially misleading to combine them within a single function. A Boolean flag should control a simpler, smaller distinction. And indeed, many would argue that you should never write functions that accept booleans that switch between different modes of behavior; those should always be different functions.

Finally, from an implementation perspective, I think it’s a good indicator that you should split up your function into two functions if the two behavior paths share absolutely or almost no code in common, which would be the case here.

[subsetpark]

for some more reading, a discussion on the Boolean parameter (anti)pattern:

https://understandlegacycode.com/blog/what-is-wrong-with-boolean-parameters/

https://softwareengineering.stackexchange.com/questions/147977/is-it-wrong-to-use-a-boolean-parameter-to-determine-behavior

[uvtc]

Thank you, @subsetpark !

[greenfork]

I think there's another example, functions:

• all
• any?
• some
• every?

They have very similar semantics, it's probably better to unify their syntax as well.

[uvtc]

I tried to sum up the naming issues here:

• For top-level functions that return a new modified copy (including map, filter, etc.), it would be a mess to try and change their names to be "ed"-suffixed. So that's unlikely to happen.

• As @bakpakin points out, it would also be a mess to try and tack on a "!" to side-effecty functions, and so that's not happening either.

• Since Janet has mutable and immutable ds variants, it would only make sense to have "ed"-suffixed names under the mutable names, as in "table/" and "array/". But you can't have silliness like "string/frob" and "buffer/frobbed" doing the same thing.

• Although there's some prior art (lisps using "!" and Python using "ed"-suffixed functional variants), Janet is somewhat novel in that it has both mutable and immutable varieties of its data structures.

So the answer is just that naming is difficult. reverse! was a good choice for the side-effecty version, given that: (A) you've got string/reverse that returns a new copy, and (B) reverse is consistent with string/reverse.

sort doesn't have that same issue, and so you've got the "ed"-suffixed varieties for the functional versions.

Perhaps this issue can be closed, and then if someone has a specific case where naming could be improved, a separate issue could be created for that case.