sneak
e97b48eea4
All checks were successful
check / check (push) Successful in 9s
- Move title and last_modified to YAML front matter (all policy docs) - Make all document sections H1, subsections H2 - Update version rule to reference front matter format - Fix "our" → "your" typo in Go styleguide - Fix Python styleguide numbering (2. → 1.) - Fix README: "flat collection" → accurate description, remove stale TODO - Remove Makefile items from code styleguides (repo stuff, not code), add note linking to Repository Policies - Change zerolog → slog in Go styleguide - Fix JS styleguide npm reference: both work, but use make targets - Drop .json from healthcheck path, add JSON content-type requirement - Add Author/License to Go HTTP Server Conventions - Convert hyperlinks to backtick URLs in checklists for consistency - Add version/front matter to both checklists
85 lines
3.4 KiB
Markdown
85 lines
3.4 KiB
Markdown
---
|
|
title: Code Styleguide
|
|
last_modified: 2026-02-22
|
|
---
|
|
|
|
# All
|
|
|
|
1. Every repo must have a `Makefile` and a `Dockerfile`. See
|
|
[Repository Policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md)
|
|
for required targets and conventions.
|
|
|
|
1. For F/OSS-licensed software, try to include the full source code of the
|
|
current version (and any dependencies, such as vendored dependencies) in the
|
|
docker image. They're small and should be included with the binary.
|
|
|
|
1. Under no circumstances should any credentials or secrets ever be committed to
|
|
any repository, even private ones. Store secrets in environment variables,
|
|
and if they are absolutely required, check on startup to make sure they are
|
|
set/non-default and complain loudly if not. Exception, sometimes: public
|
|
keys. (Public keys can still sometimes be secrets for operational security
|
|
reasons.)
|
|
|
|
1. Avoid nesting `if` statements. If you have more than one level of nesting,
|
|
consider inverting the condition and using `return` to exit early.
|
|
|
|
1. Almost all services/servers should accept their configuration via environment
|
|
variables. Only go full config file if absolutely necessary.
|
|
|
|
1. For services/servers, log JSON to stdout. This makes it easier to parse and
|
|
aggregate logs when run under `docker`. Use structured logging whenever
|
|
possible. You may detect if the output is a terminal and pretty-print the
|
|
logs in that case.
|
|
|
|
1. Debug mode is enabled by setting the environment variable `DEBUG` to a
|
|
non-empty string. This should enable verbose logging and such. It will never
|
|
be enabled in prod.
|
|
|
|
1. For services/servers, make a healthcheck available at
|
|
`/.well-known/healthcheck`. The response must have a
|
|
`Content-Type: application/json` header and return a JSON object containing
|
|
the service's name, uptime, and a key of `"status"` with a value of `"ok"`.
|
|
Return a 200 for healthy, 5xx for unhealthy.
|
|
|
|
1. If possible, for services/servers, include a /metrics endpoint that returns
|
|
Prometheus-formatted metrics. This is not required for all services, but is a
|
|
nice-to-have.
|
|
|
|
# Bash / Shell
|
|
|
|
1. Use `[[` instead of `[` for conditionals. It's a shell builtin and doesn't
|
|
have to execute a separate process.
|
|
|
|
1. Use `$( )` instead of backticks. It's easier to read and nest.
|
|
|
|
1. Use `#!/usr/bin/env bash` as the shebang line. This allows the script to be
|
|
run on systems where `bash` is not in `/bin`.
|
|
|
|
1. Use `set -euo pipefail` at the top of every script. This will cause the
|
|
script to exit if any command fails, and will cause the script to exit if any
|
|
variable is used before it is set.
|
|
|
|
1. Use `pv` for progress bars when piping data through a command. This makes it
|
|
easier to see how much data has been processed.
|
|
|
|
1. Put all code in functions, even a main function. Define all functions then
|
|
call main at the bottom of the file.
|
|
|
|
# Docker Containers (for services)
|
|
|
|
1. Use `runit` with `runsvinit` as the entrypoint for all containers. This
|
|
allows for easy service management and logging. In startup scripts
|
|
(`/etc/service/*/run`) in the container, put a `sleep 1` at the top of the
|
|
script to avoid spiking the cpu in the case of a fast-exiting process (such
|
|
as in an error condition). This also limits the maximum number of error
|
|
messages in logs to 86400/day.
|
|
|
|
# Author
|
|
|
|
[@sneak](https://sneak.berlin)
|
|
<[sneak@sneak.berlin](mailto:sneak@sneak.berlin)>
|
|
|
|
# License
|
|
|
|
MIT. See [LICENSE](../LICENSE).
|