diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0e09b5b4c5a8dac8ebfc37ab89581aea447e0671..577bcb9585838c96ecbc30129ac41f642f8ca17e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,4 @@ -# Contributing to FC pregmod +# Contributing to FC: Pregmod First off, thanks for taking the time to contribute! @@ -46,21 +46,93 @@ rules from `.eslintrc.json`. * prefer strict equality/inequality * etc. -### JSDoc +### Documentation -It's a good idea to provide meaningful JSDoc for new functions and classes where possible. We follow Typescript's JSDoc -type dialect for the most part (and we provide a Typescript configuration and auxiliary type definition files if you'd -like to use it yourself...it's pretty nifty). Don't worry too much about specific type syntax if you can't make TS work -or don't understand it, someone else will probably fix it for you as long as you've made the intent clear in some form -of JSDoc. +It's a good idea to provide meaningful documentation for new functions and classes where possible. We follow +Typescript's [JSDoc](https://jsdoc.app) type dialect for the most part (and we provide a Typescript configuration and +auxiliary type definition files if you'd like to use it yourself – it's pretty nifty). Don't worry too much about +specific type syntax if you can't make TS work or don't understand it, someone else will probably fix it for you as long +as you've made the intent clear in some form of JSDoc. ### Naming conventions -* JS names are camelCase `fooBar` - * initial lowercase for variables and functions `fooBar` - * initial uppercase for classes and namespaces `Foo.Bar` - * all-caps for constants -* CSS classes are kebob-case. `foo-bar` +* JavaScript variable and function names should be `camelCase`. + +```js +// bad +let foobar; +let Foobar; +let FooBar; + +// good +let fooBar; +``` + +* Enum members should be `ALLCAPS`. + +```ts +// bad +enum Foo { + bar = 'bar', + Baz = 'baz', +} + +// good +enum Foo { + BAR = 'bar', + BAZ = 'baz', +} +``` + +This also applies to JavaScript objects that are used as enums. + +```js +// bad +/** @enum {string} */ +const foo = { + bar: 'bar', + Baz: 'baz', +} + +// good +/** @enum {string} */ +const foo = { + BAR: 'bar', + BAZ: 'baz', +} + + +// better +/** @enum {string} */ +const Foo = { + BAR: 'bar', + BAZ: 'baz', +} +``` + +* JavaScript classes and namespaces should be `PascalCase`. + +```js +// bad +class foo {} +class FOO {} +App.foo.bar(); + +// good +class Foo {} +App.Foo.bar(); +``` + +* CSS classes are `kebob-case`. + +```css +/* bad */ +.fooBar {} +.FOO-BAR {} + +/* good */ +.foo-bar {} +``` New code should generally get organized into the `App` namespace. See `js/002-config/fc-init-js.js` for a rough outline. @@ -94,8 +166,8 @@ errors, it's not totally clean as is and there are a few false positives. ## Wiki Files * Writing Guides - * [Twine (Twine is being phased out of the project however the concepts are still relevant.)](devNotes/scene-guide.txt) - * [JS](devNotes/jsEventCreationGuide.md) + * [Twine (Twine is being phased out of the project however the concepts are still relevant)](devNotes/scene-guide.txt) + * [JavaScript](devNotes/jsEventCreationGuide.md) * [Exception handling](devNotes/exceptions.md) * [Sanity check](devNotes/exceptions.md) * [Slave List](devNotes/slaveListing.md) @@ -105,7 +177,7 @@ errors, it's not totally clean as is and there are a few false positives. * [Limbs](devNotes/limb functions.md) * [Standalone functions](devNotes/standaloneFunctions.md) * [Some potentially useful JS functions](devNotes/usefulJSFunctionDocumentation.txt) - * [Content embending chart](devNotes/contentEmbendingChart.png) (for more detail refer to https://gitgud.io/pregmodfan/fc-pregmod/-/merge_requests/7453#note_118616) + * [Content embedding chart](devNotes/contentEmbeddingChart.png) (for more details refer to https://gitgud.io/pregmodfan/fc-pregmod/-/merge_requests/7453#note_118616) ## Useful issues diff --git a/devNotes/contentEmbendingChart.png b/devNotes/contentEmbeddingChart.png similarity index 100% rename from devNotes/contentEmbendingChart.png rename to devNotes/contentEmbeddingChart.png