CONTRIBUTING.md · Oversight

21 lines · markdown

# Contributing
 
## Code style
 
Oversight is security protocol code, so implementation files should read like
code first.
 
- Prefer clear names, small functions, and tests over explanatory inline
  comments.
- Do not add prose comments for ordinary control flow, configuration loading,
  route setup, or obvious validation.
- Keep comments only when they document a non-obvious protocol invariant,
  external wire-format requirement, compatibility constraint, or security
  boundary that code alone cannot make explicit.
- When a comment is necessary, keep it short and factual. Avoid conversational
  sentences and implementation diary notes.
 
Public documentation belongs in `docs/`, not in source-file commentary.
 
The strictest paths are enforced by `scripts/check_source_comments.py`; run it
before pushing changes in the Rust registry.

1	# Contributing
2
3	## Code style
4
5	Oversight is security protocol code, so implementation files should read like
6	code first.
7
8	- Prefer clear names, small functions, and tests over explanatory inline
9	comments.
10	- Do not add prose comments for ordinary control flow, configuration loading,
11	route setup, or obvious validation.
12	- Keep comments only when they document a non-obvious protocol invariant,
13	external wire-format requirement, compatibility constraint, or security
14	boundary that code alone cannot make explicit.
15	- When a comment is necessary, keep it short and factual. Avoid conversational
16	sentences and implementation diary notes.
17
18	Public documentation belongs in `docs/`, not in source-file commentary.
19
20	The strictest paths are enforced by `scripts/check_source_comments.py`; run it
21	before pushing changes in the Rust registry.