Archipelago/docs/style.md

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. 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 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.

  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.
• Worlds that do not follow PEP8 should still have a consistent style across its files to make reading easier.
• Match statements 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 gotos, 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. 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 to avoid polluting global scope.
• Prefer to use defer in script tags, which retains order of execution but does not block.
• Avoid <script async ... in most cases, see 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 where appropriate (quotation marks, indentation).
• When escaping a line break, add a space between code and backslash.