Project Refactoring Guidelines

Generic workflow for refactoring, testing, documenting, and creating examples for Dart/Flutter modules.

---

Overview

This document defines a systematic approach to refactoring modules with quality gates at each phase. The workflow ensures code quality, comprehensive documentation, working examples, and thorough test coverage. 

┌─────────────────────────────────────────────────────────────────────────────┐
│                         REFACTORING WORKFLOW                                │
└─────────────────────────────────────────────────────────────────────────────┘

For each module:
       │
       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  1. Refactor    │ ──► │  2. Document    │ ──► │  3. Examples    │
│     Code        │     │     Code        │     │                 │
└─────────────────┘     └─────────────────┘     └─────────────────┘
       │                        │                        │
       ▼                        ▼                        ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  4. Tests       │ ──► │  5. API Docs    │ ──► │  6. Quality     │
│                 │     │                 │     │     Review      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
       │
       ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    Repeat until all issues resolved                         │
└─────────────────────────────────────────────────────────────────────────────┘

---

Phase 1: Code Refactoring

Step 1.1: Analyze Current State

1. Read all files in the target module folder 2. Identify public API surface (classes, methods, members) 3. Check current test coverage and examples 4. Review usage in reference projects for real-world patterns

Step 1.2: Refactor Code

Apply coding guidelines from coding_guidelines.md:

1. Preserve public API - Do NOT change functionality or remove/add public methods, members, or accessors 2. Private members OK - May introduce new private members, methods, and accessors for clarity 3. Follow coding guidelines - Apply consistent formatting, naming, and structure 4. Fix obvious bugs - Correct any bugs found during refactoring 5. Run dart analyze - Fix all analyzer warnings and errors

Step 1.3: Quality Check - Refactoring

  • [ ] No public API changes (same classes, methods, signatures)
  • [ ] All files follow coding guidelines
  • [ ] No analyzer warnings or errors
  • [ ] Code is more readable and maintainable

---

Phase 2: Documentation

Step 2.1: Create Module Documentation

Follow documentation_guidelines.md:

1. Create {module_name}.md in doc/ folder (e.g., doc/http_connection.md) 2. Length should match module complexity 3. Include code samples that will be extracted to examples 4. Document all public classes, methods, and members

Step 2.2: Quality Check - Documentation

  • [ ] All public classes documented
  • [ ] All public methods documented
  • [ ] All public members documented
  • [ ] No features described that don't exist in code
  • [ ] Code samples are accurate and runnable
  • [ ] Cross-references to related modules are correct

---

Phase 3: Examples

Step 3.1: Create Examples

Follow examples.md:

1. Examples must be executable code, not printed console output 2. Number of examples should cover all important functionality 3. Reference usage in client/server projects for real-world patterns 4. Include assertions to verify expected behavior

Step 3.2: Quality Check - Examples

  • [ ] Examples are executable (not just printed)
  • [ ] Examples cover all public classes
  • [ ] Examples cover typical usage scenarios
  • [ ] Examples run without errors
  • [ ] Examples demonstrate real-world patterns

---

Phase 4: Tests

Step 4.1: Create Tests

Follow tests.md:

1. Test all public functionality 2. Add files to build.yaml if reflection is needed 3. Import and initialize reflection as required 4. Use proper group hierarchy and descriptive names

Step 4.2: Quality Check - Tests

  • [ ] Tests cover all public methods
  • [ ] Tests cover edge cases
  • [ ] All tests pass
  • [ ] Mocking is appropriate for external dependencies

---

Phase 5: API Documentation

Step 5.1: Create API Summary

Create comprehensive API documentation following these guidelines:

DocumentPurpose
api_summary_creation.md Rules for creating api_summary_{module}.md user documentation
api_reference_creation.md Process for combining summaries into PDF

1. Create api_summary_{module}.md in doc/api/ folder 2. Document all public classes, methods, and global variables 3. Update api_summary_index.md with new module

Step 5.2: Quality Check - API Documentation

  • [ ] API summary lists all public classes
  • [ ] API summary lists all public methods with signatures
  • [ ] API summary lists all global functions and constants
  • [ ] No private members documented
  • [ ] Documentation matches actual code

Step 5.3: Create Combined Documentation

After all individual module documentation is complete, create a combined project documentation file:

Combined Document Structure

{project_name}_documentation.md
├── Table of Contents (auto-generated for combined doc)
├── Part I: API Summary
│   └── Content from api_summary_index.md
├── Part II: API Reference
│   ├── Module 1 API (from api_summary_{module1}.md)
│   ├── Module 2 API (from api_summary_{module2}.md)
│   └── ...
└── Part III: Module Guides
    ├── Module 1 Guide (from doc/{module1}.md)
    ├── Module 2 Guide (from doc/{module2}.md)
    └── ...

Assembly Process

1. Create new combined file with YAML front matter:

   ---
   title: "{Project Name} Documentation"
   date: "{date}"
   toc: true
   toc-depth: 2
   ---

2. Add Part I: API Summary - Copy content from api_summary_index.md

3. Add Part II: API Reference - For each module: - Copy content from doc/api/api_summary_{module}.md - Adjust headline levels using md_headline_indent.sh script - Each module becomes a subsection (level 2 heading)

4. Add Part III: Module Guides - For each module: - Copy content from doc/{module}.md - Adjust headline levels so each module is a subsection - Module guides become subsections (level 2 heading)

5. Adjust headline levels throughout so the document is properly structured: - Part titles: # (level 1) - Module names: ## (level 2) - Original # headings: ### (level 3) - Original ## headings: #### (level 4)

Use the headline indentation script to adjust levels:

# Indent all headlines by 2 levels (# becomes ###)
./_bin/md_headline_indent.sh -i 2 input.md > output.md

# Indent by 1 level (# becomes ##)
./_bin/md_headline_indent.sh -i 1 input.md > output.md

Quality Check - Combined Documentation

  • [ ] Table of contents reflects combined structure
  • [ ] All module API summaries included as subsections
  • [ ] All module guides included as subsections
  • [ ] Headline hierarchy is consistent (no jumps)
  • [ ] Internal links still work or are updated

---

Phase 6: Final Quality Review

Comprehensive Verification

1. Code Review - Run dart analyze - no errors or warnings - Run dart test or flutter test - all tests pass - Run examples - all execute successfully

2. Documentation Review - Read generated documentation - Verify all public API is documented - Extract code samples and verify they run

3. Coverage Review - Verify tests cover all public methods - Verify examples cover typical usage - Verify documentation covers all features

4. Cross-Reference Review - Check reference project usage matches examples - Verify patterns are consistent across modules

Issues Found?

If any issues are found during quality review:

1. Document the issue 2. Return to the appropriate phase 3. Fix the issue 4. Repeat quality review

---

Project-Specific Guidelines

Some projects have local _copilot_guidelines/ folders with project-specific workflows:

ProjectLocal GuidelinesReference Projects
tom_core_flutter tom_core_flutter/_copilot_guidelines/ tom_uam_client, tom_uam_shared
tom_core_server tom_core_server/_copilot_guidelines/ tom_uam_server, tom_uam_shared
tom_core_kernel tom_core_kernel/_copilot_guidelines/ tom_uam_client, tom_uam_server

Check for a local _copilot_guidelines/ folder in the target project for:

  • Module lists specific to that project
  • Reference projects for understanding usage patterns
  • Project-specific workflow adjustments

---

Reference Guidelines

TopicDocument
Coding standards coding_guidelines.md
Documentation structure documentation_guidelines.md
Test creationtests.md
Example creation examples.md
API summary creation api_summary_creation.md
API reference PDF api_reference_creation.md
D4rt bridgingd4rt/BRIDGING_GUIDE.md

---

Quick Reference Prompt

Use this prompt to start a full module refactoring session:

I want to refactor the {module_name} module in {project_name}.

Follow project_refactoring_guidelines.md:
1. Refactor code following coding_guidelines.md
2. Create documentation following documentation_guidelines.md
3. Create examples following examples.md (must be executable)
4. Create tests following tests.md
5. Create API documentation following api_summary_creation.md
6. Perform quality review for each phase

Reference {reference_project} for real-world usage patterns.
Do not change public API surface.
Repeat quality checks until all issues are resolved.