Coding guidelines & 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, Scala, Groovy, and Kotlin, the IntelliJ formatter settings can handle most 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.