Conventions¶

Contents

APIs: REST APIs and data representation

Documentation: Writing and maintaining documentation

Java: Java and Kotlin conventions

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

### File names: See https://dmyersturnbull.github.io/ref/style/documentation#filenames

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 dmyersturnbull/cicd. 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).

History¶

Comming soon…