Naming Convention

[machaval]

Functions in DW

Naming is one of the hardest things and more subjective things in programing languages. Over the years we have added functions into
the DW language without a clear guideline and we have spent to many hours discussing the naming of them. The idea of this document is
to have a guideline (it doesn't need to be perfect) so that we can have consistent naming. The idea is that we will look for new functions will be adopted without our consumers to suffer for the least astonishment principle.

We should also define some guidelines for how parameters should be set (order), kind overloading and lambdas.

Basic principles

• We will optimize naming for readability
• We should try to handle edge cases as smooth as possible (Null I'm looking at you)
• We should design for composability and extensibility (Lambdas when possible)

Binary functions

Binary functions (functions with two params) are the most common type of functions in DW. We should optimize this functions
for infix notation. What does this mean.

1. First parameter MUST be the value where we will operate over.
2. This allows us to do chaining with other functions
3. We should optimize for how this is readable.
4. We should handle the null case when possible to make the chaining case simple
5. Should we use a verb+connector pattern?

Examples:

Let's look at some examples from the dw::core::Arrays

fun splitWhere<T>(array: Array<T>, condition: (item: T) -> Boolean): Pair<Array<T>, Array<T>> 

fun splitWhere(array: Null, condition: (item: Nothing) -> Any): Null

Usage:

["Test", "Jul", "Jun"] splitWhere (item) -> item startsWith "Jul"

• It uses a connector word like where so that is easy to read it has a verb and a connector.
• It handles the null case so that we can easily chain it

On the other case we have partition

fun partition<T>(array: Array<T>, condition: (item: T) -> Boolean): : {success: Array<T>, failure: Array<T>}
fun partition(array: Null, condition: (item: Nothing) -> Any): Null

Though partition handles the null case the name doesn't follow the verb connector, so it is incosistent.
Usage:

[0,1,2,3,4,5] partition (item) -> isEven(item)

In this case we should have follow a verb+connector like partitionWhen

Unary Functions

Unary functions are always prefix so here we should try to optimize readability for prefix case.

• Use from and to prefix for type transformation cases i.e fromBase64
• Use of for getting properties of a value i.e sizeOf valuesOf keysOf

Other cardinality

There has been cases where other cardinality functions has been transformed to binary functions, an example of this is the
replace by using the with function connector. Though I think the end result reads really well it is very hard to understand the
signature and how they all work together

"a----b" replace "-" with ""

Very simple to read but very hard to understand that you need to use the with function unless you read the documentation.

I'm still not sure if we should follow this pattern that it has been also used on dw::util::Values in functions like update or mask.

Instead a function like replaceWith("a----b", "-", “") it also reads good (follow the verb+connector) and it is not hard to understand how it works.

[Shadow-Devil]

I personally think that this verb+connector should not be added to every binary operation (thinking about mapWhere or filterWhere which seem quite verbose to me). I do like the splitWhere since split has two variants splitWhere and splitBy. If for example we would have second variant of partition (like pertitionBy) I would also think this naming schema would work quite well by renaming the original partition into partitionWhere. Otherwise the connector seems to add a lot of verbosity (in my opinion).

[claytonflesher]

I think I agree with your reasoning here. Only add the connector when it improves clarity or the verb is being used already or in another situation. The only thought that arises for me on that is, it may not always be clear when creating the initial verb function that it might get reused again and need a connector in the future. So you may end up in a situation where you have a split and splitWhere situation if you don't always use the connector initially, which might be even more confusing in the long run.

[tonedef71]

As a suggestion, I would like to recommend that any DataWeave function or operator which expects a lambda function and iterates over a given list should always provide the current index as one of its lambda calling arguments.

For example, mapObject((value, key, index) -> ...) does that, and I wish reduce((item, accumulator) -> ...) had done that, too.

[claytonflesher]

On the Binary Functions section, I want to reiterate the importance of infix notation. This chain-ability makes code so much more readable and clean. I'd say any function that takes more than two arguments, such as rightPad or substring, should ALSO always have the first item be the value or collection to be acted upon. Ideally, even those functions could be made to support infix notation at some point in the future. 🤞

Even if they can't, the consistency of the argument pattern is important. Developers shouldn't have to go read the docs every time they want to remember the order of arguments for a function.