forked from coracle/caravel
Jon Staab
45 lines
2.7 KiB
Markdown
45 lines
2.7 KiB
Markdown
# Style guide
|
|
|
|
## Comments
|
|
|
|
Keep comments minimal, one line if possible.
|
|
|
|
There is one right place to document any given information:
|
|
|
|
- Functions should have a doc comment explaining the purpose of the function, not its implementation.
|
|
- Only very strange behavior should be documented using non-doc comments.
|
|
- Models and their fields are documented in models.rs, not in migrations, implementations, or anywhere on the frontend.
|
|
- Database indexes are documented in migrations.
|
|
|
|
## Data Modeling
|
|
|
|
When naming a foreign key, always use `{model}_{pk}`, for example `relay.tenant_pubkey`.
|
|
|
|
When referring to a tenant's pubkey, always name it `tenant_pubkey`, not `tenant` or `pubkey`. The exception to this is when we're in a context where we're already talking about tenants, e.g. `tenant.pubkey`, `get_tenant(pubkey)` or any tenant-related routes.
|
|
|
|
## Migrations
|
|
|
|
Pre-release: squash schema changes into `0001_init.sql` rather than adding new migration files. Once released, migrations become append-only.
|
|
|
|
## Markdown
|
|
|
|
Do not hard-break markdown files at a certain number of characters. Allow readers to implement line wrapping naturally instead.
|
|
|
|
## Rust
|
|
|
|
Prefer `&str` over `&String` for function parameters — `&str` accepts both `&String` (via deref coercion) and string literals, so it's strictly more flexible. Only take `String` when you need ownership (storing in a struct, mutating, or transferring ownership).
|
|
|
|
Avoid passing `&mut` to functions. The performance improvement often comes at the cost of poor abstraction boundaries and error prone business logic. Instead, return results to the caller which can manage mutability itself, or re-calculate/fetch mutable data.
|
|
|
|
Don't be overly DRY. Deep call trees are harder to read; factoring functions into many tiny pieces means that function boundaries are defined less by the domain or the responsibility of a given piece of code than by coincidental similarity. New functions should be created when 1. they represent a different concern that is the responsibility of a different part of the codebase, 2. the contained logic is repeated 3+ times, or 3. the contents of the function are complex and naming them makes the logical flow of the code easier to follow.
|
|
|
|
## Verification
|
|
|
|
Check justfile and frontend/package.json for common commands for linting/building.
|
|
|
|
## Skills
|
|
|
|
Skills should be created and maintained when updating the codebase. Before creating a skill, check to see if a relevant one already exists.
|
|
|
|
Avoid including code in skills unless the purpose of the skill is to illustrate coding principles; architecture and domain should be explained in plain English and provide a high-level overview of the topic without going into implementation details.
|