Style Guide / Code Formatting

[tobanteAudio]

For future contributions, it would probably be very helpful to have a common style guide for source files (JavaScript, C++ & Markdown).

For C++ the only real option is clang-format, which is really nice once you find a config that you like.

For JavaScript and Markdown, there are more options. The one that I'm familiar with is Prettier, which does both JS & MD.

We could add a script which runs both tools on the source files.

Is this something you are interested in?

[nick-thompson]

💯 absolutely. I think that would be helpful even just for me, but also to lower the overhead for any interested contributors.

To be honest, I'm not very well versed in either Prettier or clang-format, but I've seen them both around a bunch. I've tried to keep pretty close to the JUCE code style in my C++ but my JavaScript formatting has just been habitual. If we can roughly formalize the existing style into a config setting for clang-format and prettier then I think that'd be perfect. Do you want to give it a try?

[JoshMarler]

@nick-thompson , definitely needed for beta?

[nick-thompson]

100%, let's add it (edit: keep it)

[nick-thompson]

Quick update here, @olidacombe has some work with Prettier going on the js side in #191.

This morning, I'm looking at clang-tidy and clang-format to cover the C++ side. Should be pretty easy to integrate these things into our workflow, but a prerequisite for clang-format seems to be picking and adhering to a .clang-format style. I'm not very well-versed in these, so figured I'd ask here: anybody familiar with some .clang-format options that land pretty close to the way the code is generally formatted in our codebase already?

[JoshMarler]

Not sure if you've seen this Nick but worth a look: https://forum.juce.com/t/automatic-juce-like-code-formatting-with-clang-format/31624/7

Granted we might not want to match juce's coding style exactly.

[nick-thompson]

Excellent, I'll poke at that later this week! Thanks

[olidacombe]

I am finding myself thinking about style guidance again in the context of props defined for core js components. TextInputProps is a good example, where there's a mixture of cases for the props (some are camelCase, some kebab-case). Although it's perhaps not worth losing sleep over, I think having consistency in the interface exposed to clients has value. What we've done with css props is convert to kebab-case when crossing to C++, so clients have a choice of case, and we use camelCase in the examples. If we want to "go consistent", 2 options are:

• 1 use, say, camelCase as the standard in js-land, convert css props on the way to C++ (like we do) for yoga's benefit, and define our juce::Identifiers on native components using camelCase by convention. Implicitly there's a choice of case for css props, but for core component props camelCase would be your only choice.
• 2 use something like https://github.com/kimamula/ts-transformer-keys to pull a list of all prop keys defined on components in the npm package, so that's available to amend the list of keys which auto-convert to kebab-case on the way over to C++. Then we can continue to offer a choice of cases on the js side. This option is a little dumb perhaps because the typescript interfaces are going to offer you camelCase and not kebab-case so the flexibility basically has no value.

I seem to have talked myself out of option 2. But I think consistency in the api (i.e. core component props) is a good idea.

[nick-thompson]

Thanks @olidacombe!

I think having consistency in the interface exposed to clients has value. What we've done with css props is convert to kebab-case when crossing to C++, so clients have a choice of case, and we use camelCase in the examples.

I very much agree, and I think option 1 is my preference here too with perhaps a slight twist: what if we just set a convention that says that within the native code, all prop names are lowercase-with-hyphen, and in javascript code we run a "convert to lowercase-with-hyphen" on every prop key. For keys that are already lowercase-with-hyphen, this transform will do nothing, and for camelcased keys it will make the appropriate transformation. That way we align on a consistent format within native (and a format that agrees with Yoga's existing convention), and allow the end user to use camelcase or hyphen-case as they please.

How does that sound?

[olidacombe]

Yes @nick-thompson that sounds ideal. And I think keeping typescript interfaces in camelCase to favour usage aligned with react native will be the right move too. But yeah, this is easy to implement, understand, and it is as flexible as the end user could want 👍🏾