Conventions¶
Contents
APIs: REST APIs and data representation
Documentation: Writing and maintaining documentation
Java: Java and Kotlin conventions
Python: Python conventions
CLI: Conventions for all CLI apps and scripts
Bash: Bash script conventions
Docker: Docker file conventions
TypeScript: TypeScript and JavaScript conventions
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¶
Whenever possible, let tools auto-format your code.
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.
Line lengths¶
Try to limit lines to ≤ 100 characters, but it’s ok if some lines are longer. If breaking a line would make the code less readable, leave it alone. Note that both Prettier and the Ruff formatter take this approach and will accept some longer lines.
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).