Style Guides, Robocop, Documentation, Naming, and Maintainability: Diagnostics, Failure Modes, and Production Practices

1. Diagnostic sequence: identify the failing layer before changing source

1. Preserve first-failure artifacts. Copy console output, formatter diff, source snapshot, Robot result files, and version manifest.
2. Confirm versions. Python, Robot Framework, Robocop, and any relevant plugin/library.
3. Confirm executed path/selection/environment/test data. Make sure the command actually scanned the files you think it did.
4. Validate parse/import graph. Use Robot dry-run; a formatter is not a parser repair mechanism.
5. Inspect variable scope and keyword resolution if the issue is semantic, not merely style.
6. Inspect library/external-system state only if the failing test touched it.
7. Inspect timing/parallel/CI/container state only when causally relevant.
8. Apply the least destructive correction and rerun the smallest controlled slice.

This ordering prevents a common failure pattern: someone sees a large Robocop output, runs formatting/fixes across the tree, and loses the exact source state that produced the original parser or runtime failure.

2. Intentionally broken example: a missing END is not a formatting defect

*** Test Cases ***
Broken Conditional
    IF    ${True}
        Log    start

Save this as a disposable broken.robot and run:

python -m robot --dryrun --outputdir evidence/broken broken.robot > evidence/broken-console.txt 2>&1
robocop check broken.robot > evidence/broken-robocop.txt 2>&1
robocop format --no-overwrite --diff broken.robot > evidence/broken-format.diff 2>&1

The first evidence is the parser/dry-run failure. Do not “repair” it by blindly applying a formatter or broad auto-fix. The semantic correction is to close the control structure with END, then rerun dry-run, lint, and format preview.

*** Test Cases ***
Broken Conditional
    IF    ${True}
        Log    start
    END

3. Failure mode: treating standalone Robotidy as the modern default

Robotidy’s formatter functionality was merged into Robocop 6, and standalone Robotidy is no longer the recommended new workflow. A legacy project may still contain commands such as robotidy tests/ or old # robotidy: off directives. Do not delete them blindly; first capture the existing output/config, then migrate intentionally to robocop format and current formatter disablers.

4. Failure mode: mass formatting without review

Current robocop format overwrites files by default. Pointing it at an entire mature repository can create a huge diff, including code owned by other teams or generated files. A large mechanical rewrite is not automatically unsafe, but it needs isolation and review.

Safer sequence:

robocop --version
robocop format --no-overwrite --diff suites resources > evidence/full-format-preview.diff
# review scope and exclusions
robocop format suites resources
robocop format --check suites resources
python -m robot --dryrun --outputdir evidence/dryrun suites

5. Failure mode: broad suppression creates false confidence

# DO NOT use this as a migration shortcut:
# robocop: off

*** Keywords ***
Legacy Everything
    Log    Every future finding in this file is hidden too

A blanket disabler removes both known debt and future diagnostics. The same problem occurs when an entire source tree is ignored merely to make CI green. Narrow the exception to a specific rule/file/line where practical and keep an exception register.

6. Failure mode: zero lint findings mistaken for good architecture

*** Keywords ***
Process Customer Lifecycle
    [Documentation]    Processes customer lifecycle.
    [Arguments]    ${customer}    ${payment_token}
    Validate Customer    ${customer}
    Charge Customer    ${payment_token}
    Delete Old Records    ${customer}
    Send Welcome Message    ${customer}

This may be perfectly formatted and may satisfy configured lint rules. It still mixes validation, money movement, destructive cleanup, and notification in one boundary. The correct diagnostic is architectural: split responsibilities, define idempotency and approval boundaries, and test irreversible operations independently.

7. Failure mode: rule/formatter churn after a tool upgrade

Suppose CI upgrades Robocop and suddenly reports new findings or a new formatter diff. First compare tool manifests and configuration. Do not immediately change source or suppress the new rules. Reproduce with the old version if available, then preview the new version. Decide whether each change is a desired policy improvement, a formatter migration, or a rule to stage later.

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

A dependency upgrade belongs in a dedicated review when possible. That keeps behavior changes attributable.

8. Failure mode: generated/vendor source is rewritten

If a formatter touches generated output, stop and inspect file-discovery configuration. Remember that directly supplied paths can override normal exclusion matching unless force-exclude is enabled. Protect generated/vendor directories with explicit exclusions and verify byte hashes before and after the style job.

9. Failure mode: names and docs are mechanically valid but ambiguous

Check Status, Validate State, and Process Data are easy to type and hard to understand. A linter cannot infer the domain entity or expected transition. Rename based on observable behavior: Order Should Be Ready For Dispatch or Build Deployment Evidence. Then update documentation to explain constraints rather than duplicate the call steps.

Duplicated prose is another drift risk. If five tests copy the same long setup explanation, the text can diverge. Put reusable contract documentation on the shared keyword/resource and let test documentation describe scenario-specific intent.

10. Performance: measure the layer that is actually slow

Robocop 9 uses caching, but cache correctness and project configuration still matter. Keep style jobs local and deterministic; do not introduce parallel-worker state merely to optimize a small repository.

11. Production anti-pattern checklist

• Standalone Robotidy as the default modern formatter.
• Running formatter overwrite across a large repository without a preview or clean VCS baseline.
• Using # robocop: off or whole-directory ignores to silence migration debt.
• Assuming “0 issues” means clean architecture.
• Floating Robocop versions independently across developer machines and CI.
• Formatting generated/vendor files that will be overwritten by their generator.
• Choosing generic keyword names that hide domain intent.
• Copying documentation that restates implementation and drifts from behavior.

Knowledge check

Summary and bridge

Reliable style governance preserves evidence, separates parser failures from static policy, treats formatter overwrites as source mutations, and refuses false-green suppressions. Lesson 5 consolidates the chapter into a checkpoint project with before/after hashes, style decisions, justified exceptions, Libdoc, CI-style exit codes, and an operator-verifiable cleanup boundary.

Current primary references

• Robocop migration to 6+ — Robotidy merge/deprecation and current disabler syntax.
• Robocop formatter — Overwrite, diff and check behavior.
• Robocop disablers — Rule/formatter-specific suppression syntax.
• Robot Framework Style Guide — Community maintainability conventions.