Conventions¶
Contents
APIs: REST APIs and data representation
Documentation: Writing and maintaining documentation
Java: Java and Kotlin conventions
JavaScript and TypeScript: JavaScript and TypeScript conventions
Python: Python conventions
Scripts and build files: Conventions for shell scripts, build files, etc.
SQL: SQL conventions
Usage¶
These docs are meant to be linked to. Include a link in your project’s readme or CONTRIBUTING.md file.
Example
See https://dmyersturnbull.github.io/style/java/
but disregard the `security:` commit type, which we don’t use.
Or just link to individual sections; e.g.
These guidelines may be too detailed for most contributors. Rather than pointing contributors here, it may be better for maintainers to enforce these rules by editing contributors’ pull requests.
Auto-formatters¶
Use the auto-formatter setup in the tyranno-sandbox repo. This includes .editorconfig, Prettier, and the Ruff formatter (which is equivalent to Black).
Prettier handles all the formatting for JavaScript, TypeScript, HTML, and CSS, and some of the formatting for Markdown and some other languages. For Java and Kotlin, the IntelliJ formatter settings can handle some of the formatting conventions for those languages.
These auto-formatters are meant to be run via pre-commit or before each merge. This document lists non-formatting guidelines (e.g. accessibility) and formatting conventions that auto-formatters do not handle.
Principles¶
Auto-formatters generally remove unnecessary syntax elements. Default options for linters tend to do the same. For example, unnecessary parentheses are stripped out. In these guidelines, I mimic that wherever possible (and reasonable).