René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"agent: use @final instead of prose to enforce non-override constraints on methods","articleBody":"## What happened\n\nWhen introducing derived methods that should not be overridden in subclasses (because a separate method is the designated override point), prose text was added to the docstrings — e.g. \"tools should override `deps_by_group` instead of this method\". A reviewer rejected this and asked to use `@final` instead.\n\n## Root cause\n\nProse documentation was chosen as the communication mechanism when Python's `@final` decorator was the correct tool. This happened because the instinct was to communicate the constraint descriptively (via docs) rather than prescriptively (via the type system).\n\n## Generalised principle\n\nWhen a method in a base class must not be overridden by subclasses, always mark it with `@final` rather than (or in addition to) documenting the constraint in prose. `@final` is enforced by type checkers and IDEs at the point of violation; prose is merely advisory and silently ignored. If a method is purely derived from another override point, `@final` makes that structural intent machine-checkable and removes the need for \"do not override\" comments entirely.\n\n## Resolution\n\nAdded `@final` to the four derived methods (`dev_deps`, `test_deps`, `doc_deps`, `get_dep_group_deps`) in `src/usethis/_tool/spec.py` and removed the prose warning from their docstrings (commit `cfef8e6`).\n\n## Follow-up\n\nNone — the fix is already applied. This lesson is filed so future agent sessions default to `@final` when enforcing non-override constraints.","author":{"url":"https://github.com/nathanjmcdougall","@type":"Person","name":"nathanjmcdougall"},"datePublished":"2026-04-09T20:23:19.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/1907/usethis-python/issues/1907"}