naming conventions: data types (Props & Options)

[rix0rrr]

We need to have a naming convention around data objects, used as (optional) keyword arguments.

They are used for three purposes:

• To configure a Construct, via its constructor (example: new Bucket(scope, id, PROPS)).
• As options to a function or method, that customize its behavior (example: eventRule.addTarget(target, TEMPLATE))
• To configure a Construct indirectly, via a method on an existing construct (example: loadBalancer.addListener(id, LISTENERPROPS))

---

In the TypeScript/JavaScript world, data objects used for configuration are usually called options or opts.

In the CloudFormation world, input data for configuring resources are called properties.

Because of our duality (mapping between programming and CloudFormation), we are split between calling these data objects properties and options.

• For the arguments to a constructor, we've most definitely settled on props, e.g. BucketProps.
• For the arguments to a method, we've varying between props and options.
• Same as for methods that construct a new construct.

---

I propose that we adopt the rule: Props for construct, Options for methods.

So in the examples above, the type names for the configuration objects would be:

• BucketProps, no change.
• AddTargetOptions.
• AddListenerOptions.

Thoughts?

[eladb]

A few notes:

• The naming convention we need is not for data types (in my mind) but more for keyword argument types. In the CDK this is almost 1:1, but just to make sure we are focused on the right semantics. To me, the missing convention is how do we call "keyword argument types".
• Another convention that will be useful to define around this is how to call "common properties". It is quite common that we need to split properties into two in order to reuse across either multiple sub-types or to allow some options to be passed in a newXxx method (but not all). API Gateway has many examples.

[rix0rrr]

The naming convention we need is not for data types (in my mind) but more for keyword argument types.

Don't really agree to disregard the type name. The argument name is positional, so doesn't really impact the code you're writing (yes, it will affect the docs and the code insight, but not the code as written). In languages like Java, the type name will be front and center as well. I do agree we need to standardize both.

Another convention that will be useful to define around this is how to call "common properties".

Agreed, and it's been floating through my mind as well. Kind of a crossover topic between this ticket and #1741 as well. I would like to (sardonically :P) point out that that discussion is about the type name as well, not about the argument name.

[eladb]

I wasn't implying to disregard the type name, just that the scope of this convention should be "what should be the type name for types that are used for keyword arguments"

[eladb]

I am leaning towards just calling everything "Options": microsoft/TypeScript#23552