From 64068eb667d2006d47d277316911d3ed42435abc Mon Sep 17 00:00:00 2001 From: Ben Gardiner Date: Sun, 20 Sep 2026 15:00:15 +0000 Subject: [PATCH] docs: update AGENTS.md coding guidelines for J1939 conventions Add guidelines regarding protocol prefixes, shared module symbols, dataclass usage, import ordering, and bindings. AI-Assisted: yes (Gemini 3.8 Flash) --- AGENTS.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 9e14bba0e1c..0cae881a67f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 `_` (e.g., `j1939_scan`, `j1939_log`), uppercase constants and registries with `_` (e.g., `J1939_GLOBAL_ADDRESS`, `J1939_MANUFACTURERS`), and classes with `` (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