Naming conventions

[aleclarson]

For the next major version, we should consider renaming some of the existing functions whose names can be confusing or hard to remember. Of course, such a breaking change is not to be taken lightly, and we need to be sure it's worth the migration effort (or provide a codemod for automatic migration).

Some examples include:

• objectify
• boil
• partob
• upperize
• …and others?

In the comments, please mention any other functions you think might need to be renamed. If you have ideas about what these functions could be named instead, please share your thoughts.

I also want to take this moment to establish naming conventions that will lead to an API that's more intuitive and readable. That leads us to some questions:

1. Is alignment with Lodash a priority when a Radashi function does the same exact thing as a Lodash function?
2. Should we adopt a to prefix for functions that convert a value from one type to another (e.g. toArray for a function that wraps a value in an array if it's not already an array)? Or do we like the ify suffix better?
3. If we decide to have multiple functions converting a value of a specific type to an object (e.g. one for array->object and one for Map->object), should we adopt a naming convention like arrayToObject and mapToObject or is there a better solution?
4. What naming guidelines can we adopt that will help us balance clarity with brevity?
5. If we decide to add “mutative” functions alongside our existing pure functions, what naming convention would be best to differentiate the two kinds of function?
6. Should we have a naming convention for async utility functions to distinguish them from sync ones?

Feel free to propose any other naming-related questions in the comments below.

[aleclarson]

I'll start with my own opinions.

1. I think aligning with Lodash wherever we have a mostly identical function is critical. Familiarity's appeal cannot be overstated. Similarly, we need to avoid using names that Lodash has claimed if the Radashi function's behavior diverges from Lodash substantially (unless it's a perfectly fitting name for the Radashi version and so Lodash is at fault for choosing it).
2. I think I'm okay with sticking to the ify suffix. Recent additions to the JavaScript stdlib have used the to prefix to mean “creates a copy that is _____” (where the blank is filled with “sorted” for toSorted or “lowercase” for toLowerCase, etc). So perhaps we should align our copy-then-mutate functions with JavaScript's naming convention and use a to prefix.
3. If we stick with the ify suffix, I think an <output-type>ify<Input-type> naming pattern could work well here (e.g. objectifyMap, objectifySet, etc).
4. Generally, I think we should prefer brevity as long as it doesn't sacrifice clarity. I assume most people will agree with me, and this principle aligns with the JavaScript stdlib. But it's not clear to me what heuristics should be used to determine the correct balance. I suppose it needs evaluation on a case-by-case basis, but I'd prefer that to not be the case as it slows down development having to wait for community feedback.
5. I think what I mentioned in my answer to 2 is relevant here. If our “create-then-mutate” functions all start with to, then mutative functions can use the verb-only naming scheme, like the JavaScript stdlib does it (e.g. Array.prototype.sort is mutative while Array.prototype.toSorted is not). That said, I'm also open to the idea of using an InPlace suffix (e.g. sortInPlace), as it clears any doubts to anyone not fully acquainted with the entirety of Radashi.
6. I don't know about this one yet. I don't think we have any functions with both an async and a sync implementation, so it might not be a relevant question (yet).

[Minhir]

5. I don't think we will have many mutative functions. One of radash(i) core principles is to be "Semi-Functional". If someone has a performance issue related to immutable functions, and they want to solve it with mutations, that case is probably very specific and util lib is not applicable in that situation. And for most use-cases, immutable to* approach brings more benefits.

[aleclarson]

@Minhir Fair point. But is using the to* naming convention still better in terms of readability? By aligning with JavaScript stdlib conventions, I assume intuitiveness improves.

[adamhamlin]

Generally I agree with what you've proposed. I'm probably the most opinionated about 2), as I don't really like the ify suffix. It works ok for objectify, because that is an actual word--tho for the uninitiated it's not super intuitive what the semantics would be. It gets more awkward once we start applying to other data structures like arrayify and mapify and setify, whereas toArray, toMap, and toSet are quite clear and this paradigm shows up in other languages too, for example, Scala.

Obviously it means we'd have to support an alias for the functions that already exist, and then probably deprecate usage of ify. So, not without extra hassle.

[aleclarson]

It gets more awkward once we start applying to other data structures like arrayify and mapify and setify, whereas toArray, toMap, and toSet are quite clear and this paradigm shows up in other languages too, for example, Scala.

Tracking this in #110