Code standards update May 2024.

[Moderocky]

Description

Our standards committee have decided upon a set of changes to code conventions and contribution standards, designed to make things a little clearer and more modern.

Some former rules have been relaxed (where we no longer felt the restrictions were helpful/necessary) and some new things have been standardised.

Overview of Changes

1. Annotations

• We will exclusively use JetBrains's annotations library going forward. We found this to be the most clearly-defined and extensive set of annotations.
• We will be a little stricter on proper annotation use (in line with JetBrains's provided instructions) to avoid incorrect compiler warnings
  • We will use contracts more
• We will mandate annotations on arrays in their proper place
• Annotations for the value (e.g. @NotNull) can now go before the value, rather than the method (e.g. public @NotNull Object myMethod())

2. Relaxing Ordering Rules

• We are relaxing the rules around import and annotation ordering a bit (just don't make it look awful, please); we felt it was slowing down pull request lifecycles for little benefit

3. Licence Header

• We will no longer require the licence header to be at the start of every file (this should save a few megabytes of space)
• If a file/package is licensed under a different licence, then its licence will need to go with it

4. Relaxing Bracket Rules

• We will be a little more relaxed about {brackets} around single-line blocks.
• Please don't abuse this or mix brackets and no brackets in the same tree (e.g. if ... else {...})

5. Ternaries

• Some ternaries are getting out of hand, and we feel this is making code unclear and illegible
  • Several mistakes were identified recently due to unclear ternary order-of-operations
• Please avoid nesting multiple (or long) ternaries where it is not necessary

6. IntelliJ Code Style File

• We plan to provide an IDE code style file for IntelliJ, which should prevent IDEs violating the rules during automatic reformat

7. Tests

• Tests are a good thing, we want more of them!
  • Unit tests for API methods
• We plan to provide contributing guides on writing tests

8. Complexity

• Long methods are okay, illegibly-complex ones are not
• We are looking at ways to measure method complexity, but please don't be afraid to break long things up into smaller chunks

---

Target Minecraft Versions: any
Requirements: none
Related Issues: none

[kiip1]

Now might also be a good time to put the .editorconfig file into proper use, by enforcing most of these conventions through it.

This will speed up PRs even further, as developers no longer need to manually adjust their IDE settings for Skript.

Links:

• https://editorconfig.org/ (General)
• https://www.jetbrains.com/help/idea/editorconfig.html (IntelliJ specific)
• https://github.com/Minestom/Minestom/blob/33dff6f458ae96eca308820f742bae240f7d88dd/.editorconfig (A good starting point, but be wary of their license)

[Moderocky]

Now might also be a good time to put the .editorconfig file into proper use, by enforcing most of these conventions through it.

Tud has already agreed to do this

[kiip1]

Sounds good then

[APickledWalrus]

just some thoughts :)