Notes_Styleguide - rpapub/WatchfulAnvil GitHub Wiki

Writing a styleguide is the ideal next step. It serves as:

  • 📜 A foundational document that explains why your rules exist
  • 🧭 A compass for contributors to follow during development or refactoring
  • 🛠️ A blueprint for your static analyzer rules to enforce

🧰 How to Structure Your UiPath Workflow Styleguide

Here’s a suggested outline tailored to your goals:

🧱 1. Introduction: Philosophy of Automation Craft

  • Emphasize modularity, testability, predictability
  • Define your vision of a “tight ship” in automation
  • Reference the metaphor: the master guiding the apprentice

🔄 2. Workflow Types and Boundaries

Type Description
Entrypoint Orchestration logic; shallow, declarative
Module Functional abstraction; no I/O, no UI elements
Unit of Work Stateless, focused logic block; pure in/out contracts

Include visual diagrams if possible — e.g., arrows showing calls, input/output shapes.

📦 3. Argument Conventions

  • Input arguments: primitive types only

  • Output must be either:

    • Result (In Dictionary<string, object>)
    • Or TransactionItem (InOut QueueItem)

  • Status allowed only as secondary output if Result or TransactionItem exists

🧪 4. Testing Expectations

  • Every unit of work must have:

    • A dedicated test case XAML
    • Valid test data set
    • Preferably ≥ 3 coverage scenarios

  • Tests must assert argument output or log observables

📏 5. Naming and Annotation

  • Argument names: in_foo, out_status, io_data (like snake_case)

  • Annotations:

    • @unit — triggers rules for argument contracts and test coverage
    • @ignore CPRIMA-XXX — used to suppress specific rules intentionally

🧰 6. Reusability & Isolation

  • No shared variables across sequences
  • No global state or shared arguments
  • Avoid deep nesting — use shallow, composed workflows

📚 7. Rule Registry (Optional)

Document each enforced rule with:

  • Name: JudgeFlowDisciplineRule
  • RuleID: CPRIMA-JFD-001
  • Description: what it checks, why it matters, examples

Here’s a clear and professional project proposal for writing a UiPath Workflow Styleguide, suitable for internal approval, stakeholder buy-in, or team alignment:

📘 Project Proposal: Authoring the UiPath Workflow Styleguide

🧭 Project Title

“Authoritative Styleguide for UiPath Workflows and Custom Analyzer Rules”

🎯 Objective

To create a comprehensive and opinionated styleguide for UiPath Studio development that defines best practices, architectural structure, and automation discipline — laying the foundation for enforceable static analyzer rules and reusable, testable workflows.

📌 Goals

  • Define clear workflow categories (e.g., entrypoints, modules, units of work)
  • Establish strict argument conventions and annotation semantics
  • Codify expectations for test coverage and reusability
  • Describe naming conventions, nesting depth limits, and modular boundaries
  • Provide human-readable documentation to back automated rules
  • Enable the onboarding of new developers into a disciplined, maintainable RPA architecture

🛠 Deliverables

Deliverable Description
styleguide.md The core styleguide, versioned and documented
Visual Diagrams (optional) Workflow role diagrams, call structures, test maps
Rule-to-Styleguide Mapping Links each CPRIMA rule to a guiding principle
Developer Quick Reference A one-pager cheat sheet for daily use
Optional: JSON index of rules Structured data for integration with CI/linter tools

🧩 Scope

This project does not include implementing the rules themselves (those already exist or are in parallel progress). It focuses on authoring the doctrinal layer that justifies and explains the rule system.

🧠 Strategic Value

  • Standardizes expectations across teams
  • Justifies static analysis outcomes in code review
  • Improves onboarding and self-service architecture understanding
  • Supports a culture of automation craftsmanship, not just coding

⏱ Timeline

Phase Duration
Research + structure outline 1 week
Draft writing 2 weeks
Internal review 1 week
Finalization + formatting 1 week

🙋 Project Lead

Proposed: [Your Name] — rule author and workflow architecture strategist

📘 CraftSpec – Opinionated Styleguide for UiPath Workflow Development (Phase 1: XAML)

0. Introduction

CraftSpec defines a maintainable, test-first approach to UiPath automation. It emphasizes modular workflows, clarity of intent, and defers irreversible actions until all validations are complete.

Designed for beginner to intermediate RPA developers, it aligns with modern UiPath Studio capabilities (Object Repository, annotations, Test Manager) and ISO/IEC 25010 software quality principles.

1. Guiding Principles

Principle Description
Input–Process–Output Workflows compute results first, write last
Modularization Extract Units of Work; isolate complexity
Observable Execution Minimum log: entry Info, exit Trace
Test Everything All execution paths in Units must be tested
Describe, Then Execute Annotations must explain purpose, args, and usage
Intellisense Over Prefixes Naming should help humans and IDEs — no enforced in_, out_
Object Repository Only No selectors in activities; only references to Object Repository items

2. Workflow Roles & Structure

2.1 EntryPoint

  • Orchestration logic only
  • Calls Process.xaml or equivalent

2.2 Process.xaml

  • Called by entrypoint
  • Accepts TransactionItem, Config, and optional request/response
  • Follows Input → Process → Output
  • Writes (files, queues, DB) only at the end

2.3 Unit of Work

  • Stateless
  • Single focused logic
  • Inputs: primitive types
  • Output: Result (Dictionary<string, object>), optional Status

2.4 Modules

  • Abstracted logic composed of Units
  • May share Config and Result logic

2.5 Helpers

  • Utility logic
  • No testing or direct invocation

🔧 TODO: Visual diagram of call structure and folder hierarchy

3. Argument and Variable Conventions

  • Arguments may use any readable naming (no enforced prefixes)
  • Inputs must be explicit — no global config reads
  • Global variables discouraged, but not banned
  • Output values must be wrapped in Result, not returned raw

🔧 TODO: Add JSON schema suggestion for Result payloads

4. Exception & Logging Strategy

4.1 Exceptions

  • Use BusinessRuleException for business logic violations (→ no retry)
  • Use System.Exception for technical errors (→ retried)
  • Never silently suppress

4.2 Logging

  • At minimum:
    • Entry: “Starting X” (Info)
    • Exit: “Finished X” (Trace)
  • Logs must help trace execution paths and aid test validation

🔧 TODO: Include standardized log message templates

5. Testing Discipline

  • Each Unit of Work must have ≥1 test case
  • Use Studio Test Panel or Orchestrator Test Manager
  • Test layout: Arrange → Act → Assert
  • Assertions via UiPath Verify activities
  • ≥3 coverage scenarios recommended

Folder structure:


/Tests/Unit/TestCase\_Foobar.xaml

🔧 TODO: Template for test scaffolding with input data format

6. Annotations and Documentation

  • Every workflow must have a root-level annotation:
    • Purpose
    • Inputs/Outputs
    • Optional: Version, Author, Dependencies
  • InvokeWorkflow activities must mirror this annotation in DisplayName or metadata

🔧 TODO: Sample annotation block with standard format

7. Snippets

  • Reusable patterns may be published as copy/paste Snippets
  • Not managed via Studio Snippet panel in Phase 1

🔧 TODO: Include snippet examples (e.g. Retry with Timeout, Safe Excel Close)

8. Rule Mapping (Workflow Analyzer)

Rule ID Name Error Level Related Section
CPRIMA-USG-001 ShouldStop Activity Check Error §4
CPRIMA-TST-001 Unit Requires Test Error §5
CPRIMA-ANN-001 Annotation Required Warning §6

🔧 TODO: Populate full rule registry

9. Related Standards and Gaps

CraftSpec draws on established quality models and engineering practices. Where alignment is partial or missing, further guidance is planned.

Standard/Principle Alignment Notes
SOLID Principles ✅ Strong Especially SRP, OCP, DIP (via modular workflows and config injection)
ISO/IEC 25010 ✅ Strong Covers maintainability, testability, modifiability
SQALE Method ✅ Partial Mirrors modularity and testability; analyzability implied
Security Best Practices ⚠️ Incomplete 🔧 TODO: Define PII handling, config secret hygiene, and robot credential isolation
Performance Optimization ⚠️ Incomplete 🔧 TODO: Establish max execution expectations, logging footprint, efficiency rules
UX and Accessibility ⚠️ Incomplete 🔧 TODO: Define guidance on logs/readability for non-devs, and standard error messages
CI/CD Integration ⚠️ Incomplete 🔧 TODO: Codify rule enforcement in pipelines, Orchestrator publishing, and test gating

10. Appendix

  • Glossary: TransactionItem, Unit of Work, Result, Status
  • Change log
  • Styleguide version

🔧 TODO: Versioning policy (e.g. CraftSpec 1.0.0)