sneak
e97b48eea4
- 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
3.4 KiB
title, last_modified
| title | last_modified |
|---|---|
| Code Styleguide | 2026-02-22 |
All
-
Every repo must have a
Makefileand aDockerfile. See Repository Policies for required targets and conventions. -
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.
-
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.)
-
Avoid nesting
ifstatements. If you have more than one level of nesting, consider inverting the condition and usingreturnto exit early. -
Almost all services/servers should accept their configuration via environment variables. Only go full config file if absolutely necessary.
-
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. -
Debug mode is enabled by setting the environment variable
DEBUGto a non-empty string. This should enable verbose logging and such. It will never be enabled in prod. -
For services/servers, make a healthcheck available at
/.well-known/healthcheck. The response must have aContent-Type: application/jsonheader 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. -
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
-
Use
[[instead of[for conditionals. It's a shell builtin and doesn't have to execute a separate process. -
Use
$( )instead of backticks. It's easier to read and nest. -
Use
#!/usr/bin/env bashas the shebang line. This allows the script to be run on systems wherebashis not in/bin. -
Use
set -euo pipefailat 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. -
Use
pvfor progress bars when piping data through a command. This makes it easier to see how much data has been processed. -
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)
- Use
runitwithrunsvinitas the entrypoint for all containers. This allows for easy service management and logging. In startup scripts (/etc/service/*/run) in the container, put asleep 1at 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
License
MIT. See LICENSE.