Skip to content

docs: update AGENTS.md coding guidelines #5188

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
BenGardiner wants to merge 1 commit into
base: master
Choose a base branch
from
+8 −1
Open

docs: update AGENTS.md coding guidelines #5188

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,14 @@
- Follow the code patterns that already exist in the file you are editing, in similar layers when editing a layer (in both `layers/` or `contrib/`) or in the rest of the project. Some of those guidelines are detailed below.
- Do not declare functions for very simple checks or operations. Prefer code readability over trying to reduce code duplication.
- Never declare a function that is only used once, unless it is meant to be a public API.
- Avoid silent exception suppression (`try: ... except Exception: pass` or bare `except: pass`). Catch specific exception types (e.g., `(AttributeError, OSError)`). When the exception is unexpected, log the caught exception using `scapy.error.log_runtime.debug(...)` or the module's child logger (e.g., `log_j1939.debug(...)`), or document explicitly why suppression is necessary. Use WARNING or above only against bugs or unexpected behaviors.
- Avoid silent exception suppression (`try: ... except Exception: pass` or bare `except: pass`). Catch specific exception types (e.g., `(AttributeError, OSError)`). When the exception is unexpected, log the caught exception using `scapy.error.log_runtime.debug(...)` or the module's child logger (e.g., `j1939_log.debug(...)`), or document explicitly why suppression is necessary. Use WARNING or above only against bugs or unexpected behaviors.
- Do not introduce backward-compatibility alias redefinitions for new or modified symbols introduced within the current branch or PR. Rename symbols directly at their original definition site and update all references across the codebase.
- Adhere strictly to protocol prefix naming conventions: prefix lowercase functions and module-level variables with `<protocol>_` (e.g., `j1939_scan`, `j1939_log`), uppercase constants and registries with `<PROTOCOL>_` (e.g., `J1939_GLOBAL_ADDRESS`, `J1939_MANUFACTURERS`), and classes with `<Protocol>` (e.g., `J1939NativeSocket`).
- Never import internal methods or constants (those starting with a leading underscore) across modules. If a function or constant is shared across multiple modules, make it public by removing the leading underscore and prefixing it with the protocol prefix.
- Dataclasses must be used strictly as dataclasses. Do not implement dictionary emulation methods (`__getitem__`, `get`, `keys`, `values`, `items`, etc.) on dataclasses. Use `dataclasses.asdict()` or attribute access when dictionary operations are required.
- Place all imports at the top of the file. Do not use local/deferred imports inside functions or methods unless strictly required to prevent circular import dependencies.
- Keep all import blocks and `__all__` lists sorted alphabetically.
- Packet layer classes (`Packet` subclasses) bound to other protocols must declare explicit `bind_layers()` bindings.

## Put code in the right place

Expand Down
Loading