Style Guides, Robocop, Documentation, Naming, and Maintainability: Configuration, Design Patterns, and Trade-Offs

1. Configuration is a team contract, not a personal editor preference

Once style commands enter CI, configuration becomes part of the repository’s executable policy. A change to pyproject.toml can make previously accepted source fail or can cause the formatter to rewrite large parts of the tree. Review it with the same care as a build configuration change.

Keep four ownership layers explicit: Robot Framework core controls parsing/execution; Robocop controls configured static/formatting policy; Python environment management selects tool versions; CI decides when/how commands are run. RobotCode/editor settings may improve developer ergonomics, but they should not be the only place where enforcement lives.

2. Decision table: common style-policy choices

3. Greenfield and migration baselines need different strategies

For a new small project, a strong baseline is cheap: adopt the formatter, enable useful linter rules, and require clean results from day one. For a large legacy repository, enabling every rule—including rules disabled by default—can produce thousands of findings and unrelated formatting changes. That destroys review signal.

A staged migration records the baseline and tightens policy deliberately: fix high-confidence parser/deprecation/safety issues first; normalize formatting in a dedicated change; then add documentation/naming/architecture-related rules in manageable batches. The target is not permanently weaker standards—the target is reviewable progress.

4. Auto-fix has three risk classes

# Preview available linter fixes without modifying files.
robocop check --diff suites resources

# Apply only fixes Robocop classifies as safe.
robocop check --fix suites resources

# Potentially unsafe fixes require an explicit extra switch.
robocop check --fix --unsafe-fixes suites resources

Current Robocop distinguishes safe fixes, unsafe fixes, and manual-only diagnostics. The important production pattern is not “always run --fix.” It is preview → classify → apply → inspect diff → run the smallest meaningful tests. Unsafe fixes may alter behavior and should never be silently executed across a repository in CI.

5. Naming is semantic compression

Robot Framework’s flexible keyword matching can normalize case, spaces, and underscores, but humans and tools still read the literal source. Choose one presentation convention for public Robot keywords—normally readable words with spaces—and reserve Python snake_case for Python implementation. Avoid two source names that normalize to the same callable name; they make lookup and review ambiguous.

6. Documentation should capture contracts that names cannot

Do not require paragraphs on every obvious helper merely because a rule exists. Instead, target reusable boundaries. Document non-obvious arguments, units, side effects, ownership, failure conditions, security assumptions, and cleanup. Keep one source of truth: if a keyword says “does not mutate state” while implementation creates a record, the documentation is worse than absent.

Libdoc is a useful review surface because it exposes keyword signatures and documentation together. In code review, regenerate or inspect Libdoc for public resources/libraries when signatures or contracts change.

7. Suppression policy: narrow, documented, temporary

[tool.robocop.lint.per_file_ignores]
"resources/legacy_adapter.resource" = ["missing-doc-keyword"]

Use a separate register such as:

Rule: missing-doc-keyword
Path: resources/legacy_adapter.resource
Reason: generated interface is being replaced; hand edits are overwritten
Owner: automation-platform
Review-by: 2026-11-01
Removal condition: adapter v2 becomes default

Inline disablers are even narrower when only one statement is exceptional. Prefer # robocop: off=rule-name over disabling all checks. The fact that a suppressor exists is itself review evidence and should be searchable.

8. Generated and vendor source: protect it explicitly

Formatter churn in generated files creates noisy diffs and may be overwritten by the generator on the next build. Exclude such paths from both lint and format unless the generator itself produces compliant source. Current Robocop also supports force-exclude so configured exclusions remain effective even if a wrapper supplies a direct file path.

[tool.robocop]
exclude = ["generated", "vendor", "evidence"]
force-exclude = true

If you control the generator, a better long-term design is to fix generation templates instead of maintaining a permanent formatter exception downstream.

9. Tool upgrades are policy changes

Robocop releases can add rules, change defaults, rename configuration, or evolve formatter output. A disciplined upgrade is a dedicated change: update the pin, record old/new versions, run lint and formatter preview, inspect new findings/diff, update suppressions only with justification, then run Robot dry-run/targeted tests. This turns “style churn” into an auditable dependency upgrade.

python -m pip show robotframework-robocop
robocop --version
robocop check suites resources > evidence/upgrade-lint.txt
robocop format --no-overwrite --diff suites resources > evidence/upgrade-format.diff

Do not let each developer independently float to latest Robocop while CI uses another version. The same repository policy should be evaluated by the same major/minor tool baseline until an upgrade is reviewed.

10. Local hooks and CI should call the same policy

A pre-commit hook can provide fast feedback, but CI is the authoritative shared gate. Avoid maintaining two different rule sets. Put the actual policy in TOML and keep wrapper commands small. For example, a local hook may run robocop check --no-project for speed while CI runs full project-level rules, but both should load the same configuration and pin.

Knowledge check

Summary and bridge

Style policy is an engineering trade-off between consistency, migration cost, diagnostic signal, and upgrade risk. Lesson 4 now stress-tests that policy with broken parser input, deprecated workflows, mass-format risk, broad suppressions, generated files, rule churn, ambiguous names, and the false assumption that zero findings equals good architecture.

Current primary references

• Robocop configuration reference — Selecting rules, per-file ignores, safe/unsafe fixes, exclusions and target version.
• Robocop disablers — Current narrow inline/block disabler syntax.
• Robocop rules — Rule IDs/names, severities and STYLE_GUIDE filter.
• Robot Framework Style Guide — Community naming and formatting conventions.