中文 | English
I. Extension Overview
The core functionality of Flow Comments is to establish "process navigation" for code through simple comments: it generates a visual process tree in the VS Code sidebar, and clicking a node will instantly jump to and highlight the corresponding code location. There's no need to modify the code structure or learn complex rules—you can use it with regular comments, achieving true "zero intrusion and low threshold."
Core Value: Significantly improves code reading and positioning efficiency, reduces the cost of switching between multiple files, and is especially suitable for development debugging, code reviews, and team collaboration scenarios.
II. Quick Start (Installation & Configuration)
2.1 Installation Steps
2.2 Core Configuration
Open VS Code Settings (shortcut: Ctrl+,), search for Flow Comments to make personalized adjustments. Explanations of key configuration items are as follows:
Prefix: The keyword used to identify process comments (default value: flow);
File Range Control: Included File Types (specify files to be scanned), Ignore Paths (skip directories that don't need parsing) to avoid invalid full-repo scanning;
Performance Optimization: Scan Concurrency Count, Maximum File Size Limit—adapt to large-scale project scenarios and ensure running speed;
Style Customization: Adjust the highlight color of the target line and the ruler prompt color after jumping.
III. Detailed Usage Guide
3.1 Basic Usage Example
Add "process comments" with the specified prefix (marking start/end and specific steps) at code locations related to functions, as shown below:
// flow-login start // Mark the start of the "login function" process
// flow-login 1 Enter username // Step 1: Enter username
const inputUsername = (val) => { /* Business logic */ }
// flow-login 2 Enter password // Step 2: Enter password
const inputPassword = (val) => { /* Business logic */ }
// flow-login end // Mark the end of the "login function" process
Entry Point: Open the Flow Comments panel in the VS Code sidebar to view the generated Flow Tree. You can browse processes by function group and click any node to jump to the corresponding code line with one click.
3.2 Hierarchical Usage Skills
Supports setting step hierarchies through "dots" to achieve structured display of complex processes. Core rules are as follows:
Hierarchy Format: Example 1 (Level 1) → 1.2 (Level 2) → 1.2.3 (Level 3). The Flow Tree will automatically group and expand by hierarchy;
Process Boundaries: Clearly add start (beginning) and end (end) marks for each function process to ensure a clear process scope;
Sorting Rule: Steps are automatically sorted by hierarchical number to ensure predictable navigation logic;
Usage Suggestion: Keep step numbers consecutive, descriptions concise and clear, and maintain an independent process for each function as much as possible to avoid confusion.
3.3 View Schematic & Demo
[Usage Demo]: [Click to view GIF demo](https://github.com/catislight/vscode-flow-comments-private/blob/HEAD/Replace with actual GIF link) to intuitively understand the complete operation process such as process generation and node jumping.
IV. Core Features
Tree-Structured Visual Navigation: Concentrates process comments scattered in code into a tree structure, making the global process clear at a glance;
One-Click Precise Positioning: Click a Flow Tree node to immediately jump to the target code line and temporarily highlight it, quickly locating key logic;
Intelligent Error Reminder: Automatically detects and prompts for missing/duplicate start/end marks, duplicate step numbers and other issues, reducing usage omissions;
Large-Scale Project Adaptation: Supports precise control of scanning scope, concurrent parsing optimization, and large file skipping mechanism to ensure fast and stable operation in large repositories;
Index Persistence: Retains historical scan results, eliminating the need for full re-scanning when opening the panel or refreshing next time, improving usage efficiency.
V. Notes & Frequently Asked Questions (FAQ)
5.1 Basic Notes
Prerequisite: Ensure that the code contains process comments starting with the "configured prefix" (default: flow); otherwise, no nodes will be generated in the Flow Tree;
Compatibility: Adapts to mainstream programming languages such as Java, JavaScript, Python, and Go; for large-scale projects, it is recommended to optimize performance through "File Range Control" configuration.
5.2 Frequently Asked Questions
Q: No nodes are visible in the Flow Tree?
A: ① Confirm that the target file has added process comments that comply with the rules; ② Check if the "Included File Types" configuration covers the target file suffix; ③ Verify that the target file/directory is not added to "Ignore Paths."
Q: Slow usage experience?
A: ① Narrow down the "Included File Types" scope to retain only core business files; ② Increase the "Scan Concurrency Count" in settings; ③ Appropriately reduce the "Maximum File Size" to skip large log/configuration files.
Q: Index not synchronized after code update?
A: ① Save the modified file (automatically triggers incremental scanning); ② Manually run the command Flow Comments: Scan Active File to refresh the current file index; ③ Restart the VS Code panel.
VI. Support & Feedback
If Flow Comments is helpful for your development work, please star us on the VS Code Extension Marketplace or GitHub Repository ⭐!
If you encounter functional bugs, have optimization suggestions, or need new features, please submit feedback through the repository Issue, and we will follow up promptly.
