# Style Guide

## Generic

* This guide can be ignored for data files that are not to be viewed in an editor.
* 120 character per line for all source files.
* Avoid white space errors like trailing spaces.

## Python Code

* We mostly follow [PEP8](https://peps.python.org/pep-0008/). Read below to see the differences.
* 120 characters per line. PyCharm does this automatically, other editors can be configured for it.
* Strings in core code will be `"strings"`. In other words: double quote your strings.
* Strings in worlds should use double quotes as well, but imported code may differ.
* Prefer [format string literals](https://peps.python.org/pep-0498/) over string concatenation,
  use single quotes inside them: `f"Like {dct['key']}"`
* Use type annotations where possible for function signatures and class members.
* Use type annotations where appropriate for local variables (e.g. `var: list[int] = []`, or when the
  type is hard or impossible to deduce). Clear annotations help developers look up and validate API calls.
* Prefer new style type annotations for new code (e.g. `var: dict[str, str | int]` over
  `var: Dict[str, Union[str, int]]`).
* If a line ends with an open bracket/brace/parentheses, the matching closing bracket should be at the
  beginning of a line at the same indentation as the beginning of the line with the open bracket.
  ```python
  stuff = {
      x: y
      for x, y in thing
      if y > 2
  }
  ```
* New classes, attributes, and methods in core code should have docstrings that follow
  [reST style](https://peps.python.org/pep-0287/).
* Worlds that do not follow PEP8 should still have a consistent style across its files to make reading easier.
* [Match statements](https://docs.python.org/3/tutorial/controlflow.html#tut-match)
  may be used instead of `if`-`elif` if they result in nicer code, or they actually use pattern matching.
  Beware of the performance: they are not `goto`s, but `if`-`elif` under the hood, and you may have less control. When
  in doubt, just don't use it.

## Markdown

* We almost follow [Google's styleguide](https://google.github.io/styleguide/docguide/style.html).
  Read below for differences.
* For existing documents, try to follow its style or ask to completely reformat it.
* 120 characters per line.
* One space between bullet/number and text.
* No lazy numbering.

## HTML

* Indent with 4 spaces for new code.
* kebab-case for ids and classes.
* Avoid using on* attributes (onclick, etc.).

## CSS / SCSS

* Indent with 4 spaces for new code.
* `{` on the same line as the selector.
* Space between selector and `{`.

## JS

* Indent with 4 spaces.
* Indent `case` inside `switch ` with 4 spaces.
* Prefer double quotation marks (`"`).
* Semicolons are required after every statement.
* Use [IIFEs](https://developer.mozilla.org/docs/Glossary/IIFE) to avoid polluting global scope.
* Prefer to use [defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script#defer)
  in script tags, which retains order of execution but does not block.
* Avoid `<script async ...` in most cases, see [async and defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script#async_and_defer).
* Use addEventListener.

## KV

* Style should be defined in `.kv` as much as possible, only Python when unavailable.
* Should follow [our Python style](#python-code) where appropriate (quotation marks, indentation).
* When escaping a line break, add a space between code and backslash.