|
1 | | -and anthropi# Sofos - AI Coding Assistant Project Context |
| 1 | +Sofos – AI Coding Assistant Project Context |
2 | 2 |
|
3 | 3 | ## Project Overview |
4 | 4 |
|
@@ -430,15 +430,15 @@ Gitignored scratchpad for helper files the user asks to be created there — typ |
430 | 430 | - Use idiomatic Rust and repository naming conventions. |
431 | 431 | - Keep code DRY and focused. |
432 | 432 | - Avoid magic strings and numbers. |
433 | | -- Keep comments short. Long, multi-paragraph narratives belong in documentation files, not in source code. |
| 433 | +- **Comments.** Non-doc comments (`//`) MUST be tight and earn their place: no unnecessary words, no restating what the code already says, plain international English, no jargon. If the comment only paraphrases the line beneath it, delete it. Doc comments (`///`, `//!`, rustdoc) MUST be professional and crystal clear — they are the public contract a reader sees in the API surface and on docs.rs, so explain purpose, invariants, error conditions, and any non-obvious caller obligations precisely and without hand-waving. |
434 | 434 | - Do not add self-explanatory comments. Doc comments (`///` and `//!`) on public APIs are the exception. |
435 | 435 | - Do not use jargon, abbreviations, or insider shorthand in comments, error messages, or documentation. Prefer wording a non-specialist reader can follow. |
436 | 436 | - Do not leave `unwrap()` or `expect()` in normal code paths. |
437 | 437 | - Use strong types where possible. |
438 | 438 | - Add or update important tests and keep them self-contained. |
439 | 439 | - After each important change, but only when you have finalized the current task, update if relevant: |
440 | 440 | - `README.md` |
441 | | - - `CHANGELOG.md` under `[Unreleased]`. Stick to the standard Keep-a-Changelog categories (`Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`) — do NOT add an `Internal` section. Pure refactors, dead-code removals, and test-only additions are not user-notable; leave them out. The changelog is for users, not contributors. Within each entry, describe the user-visible behaviour in plain English: no file paths, no bare `Type::method` shorthand, no Rust attribute syntax, no crate names. CLI flags, env vars, slash commands, and API wire formats are fine because the user encounters them directly. |
| 441 | + - `CHANGELOG.md` under `[Unreleased]`. Stick to the standard Keep-a-Changelog categories (`Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`) — do NOT add an `Internal` section. **Strictly user-facing** and held to the same writing standard as comments above: tight, plain international English, no jargon, professional and crystal clear. Pure refactors, dead-code removals, and test-only additions are not user-notable; leave them out. The changelog is for users, not contributors. Within each entry, describe the user-visible behaviour in plain English: no file paths, no bare `Type::method` shorthand, no Rust attribute syntax, no crate names. CLI flags, env vars, slash commands, and API wire formats are fine because the user encounters them directly. |
442 | 442 | - `STRUCTURE.md` |
443 | 443 | - Run: |
444 | 444 | - `cargo fmt --all` |
|
0 commit comments