Skip to content

docs(agents): add Clean Code, minimal-comments, and ASD-STE100 conventions - #11

Open
jonpspri wants to merge 1 commit into
mainfrom
docs/agents-style-conventions
Open

jonpspri wants to merge 1 commit into
mainfrom
docs/agents-style-conventions

Conversation

@jonpspri

Copy link
Copy Markdown
Collaborator

Related Issue

Style policy set directly by the maintainer (process/docs change, no bug or feature).


Summary

Adds two sets of conventions to AGENTS.md:

Code conventions (new first bullets):

  • Coding standards align with Robert C. Martin's Clean Code - intention-revealing names, small functions that do one thing, few arguments, no duplication, boring control flow over cleverness.
  • Keep comments to a minimum - code is its own documentation. Comment only what code cannot express (a security invariant, a non-obvious external contract); delete comments that restate the code.

Writing conventions (new section):

  • Project writing (README, USER_README, docs/, user-facing prose) complies with ASD-STE100 Simplified Technical English: approved words, short sentences, one instruction per sentence, active voice, present tense, one term per concept, procedures as numbered steps.

Existing conventions (import grouping, logging) unchanged.

Note: this PR and #10 touch different sections of AGENTS.md; either merge order works without conflict.


Reviewability

  • This PR has one clear purpose
  • The linked issue is not labeled triage
  • Unrelated bugs or improvements are tracked in separate issues/PRs
  • Tests are included with the code they validate (docs-only; N/A)

Type of Change

  • Documentation

Verification

Check Command Status
Tests pytest N/A (docs-only)
Lint ruff check . N/A
Type check mypy src/ N/A

Manual: reviewed rendered diff; section structure and bullet style match the existing document.


Checklist

  • Tests added/updated for changes and pytest passes (N/A docs-only)
  • ruff check . and mypy src/ are green (N/A docs-only)
  • Documentation updated
  • Commits signed off (git commit -s, DCO)
  • No secrets, credentials, or private keys committed

…tions

Codify the maintainer's style policy for agents: code follows Clean
Code and carries as few comments as possible (code is its own
documentation - comment only what code cannot express); project
writing complies with ASD-STE100 Simplified Technical English.

Signed-off-by: Jonathan Springer <jps@s390x.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant