style: strengthen constructor naming and Params struct rules

- Constructors must be New(), From<Something>(), or NewThing() (multi-type pkg)
- Strongly discourage creative names (Create, Make, Build, Init)
- Constructors must use Params struct for 2+ arguments, no exceptions
- Single obvious argument (ctx, bytes) is the only exception
This commit is contained in:
user
2026-03-17 19:53:31 -07:00
committed by clawbot
parent 1c84344978
commit e72b2d3522

View File

@@ -136,8 +136,15 @@ last_modified: 2026-02-22
1. Provide a .gitignore file that ignores at least `*.log`, `*.out`, and 1. Provide a .gitignore file that ignores at least `*.log`, `*.out`, and
`*.test` files, as well as any binaries. `*.test` files, as well as any binaries.
1. Constructors should be called `New()` whenever possible. `modulename.New()` 1. Constructors **must** be called `New()`. `modulename.New()` works great if
works great if you name the packages properly. you name the packages properly. If the constructor creates an instance from
an existing value or representation, `From<Something>()` (e.g. `FromBytes()`,
`FromConfig()`) is also acceptable. If the package contains multiple types
and `New()` is ambiguous, `NewThing()` is occasionally acceptable — but
prefer restructuring packages so each type gets its own package and a plain
`New()`. Do not invent creative constructor names like `Create()`, `Make()`,
`Build()`, `Open()` (unless wrapping an OS resource), or `Init()`. If you
see a constructor with a non-standard name, rename it.
1. Don't make packages too big. Break them up. 1. Don't make packages too big. Break them up.
@@ -149,9 +156,14 @@ last_modified: 2026-02-22
1. Use descriptive names for modules and filenames. Avoid generic names like 1. Use descriptive names for modules and filenames. Avoid generic names like
`server`. `util` is banned. `server`. `util` is banned.
1. Constructors should take a Params struct if they need more than 1-2 1. Constructors **must** take a `Params` struct (or `ThingParams` when
arguments. Positional arguments are an endless source of bugs and should be `NewThing()` is used). Positional arguments for constructors are an endless
avoided whenever possible. source of bugs — they make call sites unreadable, invite wrong-order errors
that the compiler can't catch when types coincide, and force every caller to
update when a new field is added. The only exception is a constructor that
takes exactly one argument whose meaning is obvious from context (e.g.
`New(ctx)` or `FromBytes(b)`). Two or more arguments → use a Params struct,
no exceptions.
1. Use `context.Context` for all functions that need it. If you don't need it, 1. Use `context.Context` for all functions that need it. If you don't need it,
you can pass `context.Background()`. Anything long-running should get and you can pass `context.Background()`. Anything long-running should get and