Style Guides, Robocop, Documentation, Naming, and Maintainability: Core Concepts and Mental Model

1. The problem: valid source is not automatically maintainable source

Earlier chapters established syntax, variables, imports, control flow, failure semantics, result evidence, integrations, and extension APIs. All of those mechanisms can be used in source that is technically valid yet still imposes unnecessary cognitive cost. Two teams may write the same behavior with different spacing, naming, documentation density, section order, continuation layout, or suppression conventions. A reviewer then spends time decoding presentation instead of evaluating behavior.

Style tooling exists to remove mechanical disagreement. A formatter can normalize source representation. A linter can detect patterns that are suspicious, deprecated, inconsistent, or contrary to configured rules. Neither can decide whether a keyword has one responsibility, whether a suite mutates production state safely, or whether a business-facing keyword name expresses the intended outcome. Those remain design and review questions.

2. Read-only inspection before changing a byte

python --version
python -m robot --version
robocop --version
robocop check --help
robocop format --help
robocop list rules --filter STYLE_GUIDE
robocop list formatters
python -m robot.libdoc --help

These commands establish provenance. The Python interpreter determines which Robot Framework and Robocop installations are actually used. robocop list rules --filter STYLE_GUIDE shows the rules currently connected directly to the community guide rather than relying on a remembered list. Libdoc confirms that documentation generation is available from the same Robot installation.

Record this output in CI or an evidence directory when tool upgrades matter. Style diagnostics can change between Robocop releases even when the Robot source itself did not change; without a version manifest, a sudden new finding looks like unexplained source drift.

3. Mental model: conventions become enforceable only through an explicit pipeline

flowchart TD
A[Team conventions] --> B[Parser-valid Robot source]
B --> C[Robocop formatter]
C --> D[Normalized source]
D --> E[Robocop linter / static analysis]
E --> F[Human review]
F --> G[CI style gate]
G --> H[Maintainable tests/resources]
D --> I[Libdoc]
I --> J[Keyword contract docs]
K[Runtime tests / output.xml] -. semantic evidence .-> F

The arrows are deliberately one-way. Team conventions inform source. The formatter may rewrite the source representation. The linter reads the resulting model and reports configured diagnostics. Human review evaluates meaning that static rules cannot prove. CI makes the selected mechanical policy repeatable. Libdoc is a parallel documentation artifact: it renders reusable keyword contracts, but it does not execute the suite. Runtime evidence such as output.xml is separate again; formatting success says nothing about functional correctness.

4. Vocabulary: six different quality mechanisms

5. Style Guide: guidance first, policy second

The current community Style Guide is a curated set of conventions, not a second parser grammar. For example, Robot Framework only needs two or more spaces between data cells, while the guide and the default formatter commonly use four. Source with two spaces can be valid while still differing from a team’s chosen style.

Use the guide to reduce arbitrary choice: readable keyword names, consistent variable conventions, predictable section organization, and whitespace that makes tabular structure visible. Then encode only the conventions that provide value to your project. A migration should not turn every optional recommendation into an immediate blocking rule.

6. Style tooling has its own state and ownership

A style command should normally have no reason to touch API, browser, database, SSH, RPA, or production state. That separation is valuable: run style gates before expensive or stateful functional automation and fail fast on mechanical defects.

7. Formatting is deliberately shallow

*** Keywords ***
Process Everything
    [Arguments]    ${customer}    ${order}    ${token}
    Validate Customer    ${customer}
    Create Order    ${order}
    Charge Account    ${token}
    Send Notification    ${customer}
    Write Audit Record    ${order}

A formatter can normalize spacing, continuations, line wrapping, or statement layout. It cannot decide that this keyword mixes validation, mutation, payment, notification, and auditing under one lifecycle. That requires a human design decision: separate pure validation from irreversible actions, define idempotency, isolate credentials, and expose domain-level keywords with clear failure contracts.

This distinction becomes a governance rule: format first to reduce review noise, then review semantics. Never close a maintainability issue merely because the formatter produced no diff.

8. Documentation and naming should reveal contracts, not repeat syntax

Good documentation explains what a name cannot: side effects, ownership, failure semantics, constraints, and unusual inputs. Bad documentation restates the implementation and becomes stale. A keyword named Build Order Summary may need only a short contract; a keyword that mutates a remote deployment should document target scope, idempotency, rollback, and evidence.

Libdoc turns reusable resource/library documentation into a discoverable artifact. It is especially useful for shared resources and Python libraries because reviewers can inspect signatures and prose without opening each implementation file. Treat generated Libdoc as an interface view—not proof that the interface is well designed.

9. Suppressions are exceptions with owners, not a way to make CI green

Current Robocop supports narrow inline disablers such as # robocop: off=rule-name and file-pattern-specific ignores in configuration. Use them only when the code cannot reasonably be refactored now and record the reason. A blanket # robocop: off across a directory destroys diagnostic value and hides future defects.

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

Pair such an exception with an owner, reason, review date, and removal criterion in a small exception register. The code/config says what is suppressed; the register says why and until when.

Knowledge check

Summary and bridge

This lesson separated validity, normalization, static diagnostics, documentation, and semantic review. Lesson 2 turns that model into a disposable local workflow: baseline a messy but valid project, preview formatter changes, configure Robocop, manually refactor semantic problems, generate Libdoc, and build a CI-style gate.

Current primary references

• Robot Framework Style Guide — Current community guide (0.10b at generation time).
• Robocop stable documentation — Current linter/formatter documentation.
• Robocop configuration reference — Current TOML, check, format, target-version, fix and exclusion behavior.
• Robot Framework User Guide — Stable 7.4.2 parser, resource, documentation and execution semantics.
• Libdoc — Robot Framework library/resource documentation generator.