Skip to content

Commit

Permalink
Add an FAQ item for options (#427)
Browse files Browse the repository at this point in the history
This adds an FAQ item explaining our thoughts on plugin options.
  • Loading branch information
smaye81 authored Mar 14, 2023
1 parent 826d327 commit 4684cda
Showing 1 changed file with 23 additions and 1 deletion.
24 changes: 23 additions & 1 deletion docs/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,9 @@ We generate our `enum` values based on how they are written in the source Protob

The [Buf style guide](https://docs.buf.build/best-practices/style-guide#enums) further says that `enum` values should be UPPER_SNAKE_CASE, which will result in your generated TypeScript `enum` values being in UPPER_SNAKE_CASE if you follow the style guide.

We do not provide an option to generate different cases for your `enum` values because we try to limit options to ones that we feel are important. The more options there are, the less approachable the plugin becomes. This seems to be more of a stylistic choice as even [TypeScript's own documentation](https://www.typescriptlang.org/docs/handbook/enums.html) uses various ways to name `enum` members.
We do not provide an option to generate different cases for your `enum` values because we try to limit options to ones that we feel are necessary. This seems to be more of a stylistic choice as even [TypeScript's own documentation](https://www.typescriptlang.org/docs/handbook/enums.html) uses various ways to name `enum` members.

For more information on our thoughts on options, see this [question](#options).


### Why use `BigInt` to represent 64-bit integers?
Expand Down Expand Up @@ -131,3 +133,23 @@ The main differences of the generated code:
- we implement the canonical JSON format
- we generate [much smaller bundles](packages/protobuf-bench)
- we rely on standard APIs instead of the [Closure Library](http://googlecode.blogspot.com/2009/11/introducing-closure-tools.html)

### <a name="options"></a>What is your stance on adding options to the plugin?

In general, we feel that an abundance of options tends to make the plugin less approachable. It can be daunting to a
new user to have to sift through numerous configuration choices when they are just beginning to use the plugin. Our
default position is to try to be as opinionated as possible about the generated code and this tends to result in fewer
knobs that need turned at configuration time. In addition, a plethora of options also makes debugging more difficult. It
is much easier to reason about the generated code when it conforms to a predictable standard.

There are also more concrete reasons why we prefer to add options judiciously. Consider a popular option request,
which is to add the ability to generate `snake_case` field names as opposed to `camelCase`. If we were to provide this
as an option, that means that any plugin downstream that accesses these fields or uses the base types has to also
support this option and ensure that it is set to the same value across plugins every time files are generated. In
addition, any functionality that uses the generated code must also now stay in sync. Exposing options, especially those
that affect the generated code, introduces an entirely new way for breaking changes to happen. The generated code is no
longer predictable, which defeats the purpose of generating code.

This is not to say that we are completely against adding _any_ options to the plugin. There are obviously cases where
adding an option is necessary. However, for cases such as stylistic choices or user preferences, we tend to err on the
side of caution.

0 comments on commit 4684cda

Please sign in to comment.