# PyUCC User Manual **Document Version:** 1.0 **Application:** PyUCC (Python Unified Code Counter) --- ## 1. Introduction **PyUCC** is an advanced static code analysis tool. Its primary objective is to provide quantitative metrics on software development and, crucially, to track code evolution over time through a powerful **Differing** system. ### What is it for? 1. **Counting:** Knowing exactly how many lines of code, comments, and blank lines make up your project. 2. **Measuring:** Calculating software complexity and maintainability. 3. **Comparing:** Understanding exactly what changed between two versions (added/removed/modified files and how complexity has shifted). --- ## 2. Core Concepts Before starting, it is useful to understand the key terms used in the application. ### 2.1 Baseline A **Baseline** is an instant "snapshot" of your project at a specific moment in time. * When you create a baseline, PyUCC saves a copy of the files and calculates all metrics. * Baselines serve as reference points (benchmarks) for future comparisons. ### 2.2 Supported Metrics * **SLOC (Source Lines of Code):** * *Physical Lines:* Total lines in the file. * *Code Lines:* Lines containing executable code. * *Comment Lines:* Documentation lines. * *Blank Lines:* Empty lines (often used for formatting). * **Cyclomatic Complexity (CC):** Measures the complexity of the control flow (how many `if`, `for`, `while` statements, etc.). **Lower is better.** * **Maintainability Index (MI):** An index from 0 to 100 estimating how easy the code is to maintain. **Higher is better** (above 85 is excellent, below 65 is problematic). ### 2.3 Profile A **Profile** is a saved configuration that tells PyUCC: * Which folders to analyze. * Which languages to include (e.g., Python and C++ only). * What to ignore (e.g., `venv`, `build` folders, temporary files). --- ## 3. User Interface (GUI) The interface is divided into functional zones to keep the workflow organized. 1. **Top Bar:** * **Profile** selection. * Access to **Settings** and Profile Manager (**Manage**). 2. **Actions Bar:** The main buttons to start operations (`Scan`, `Countings`, `Metrics`, `Differing`). 3. **Progress Area:** Progress bar and file counter. 4. **Results Table:** The large central table where data appears. 5. **Log & Status:** At the bottom, a log panel to see what is happening and a status bar monitoring system resources (CPU/RAM). --- ## 4. Step-by-Step Guide ### 4.1 First Run & Profile Configuration The first thing to do upon opening PyUCC is to define *what* to analyze. 1. Click on **⚙️ Manage...** in the top bar. 2. Click on **📝 New** to clear the fields. 3. Enter a **Name** for the profile (e.g., "My Backend Project"). 4. In the **Paths** section, use **Add Folder** to select your code's root directory. 5. In the **Filter Extensions** section, select the languages you are interested in (e.g., Python, Java). 6. In the **Ignore patterns** box, you can keep the defaults (which already exclude `.git`, `__pycache__`, etc.). 7. Click **💾 Save**. ### 4.2 Simple Analysis (Scan, Countings, Metrics) If you only want to analyze the current state without comparisons: * **🔍 Scan:** Simply verifies which files are found based on the profile filters. Useful to check if you are including the right files. * **🔢 Countings:** Analyzes every file and reports how many code, comment, and blank lines exist. * **📊 Metrics:** Calculates Cyclomatic Complexity and Maintainability Index for each file. > **Tip:** You can double-click on a file in the results table to open it in the built-in **File Viewer**, which provides syntax highlighting and a colored minimap (blue=code, green=comments). ### 4.3 The "Differing" Workflow (Comparison) This is PyUCC's most powerful feature. **Step A: Create the First Baseline** 1. Select your profile. 2. Click on **🔀 Differing**. 3. If this is the first time you analyze this project, PyUCC will notify you: *"No baseline found"*. 4. Confirm creation. PyUCC will take a "snapshot" of the project (Baseline). **Step B: Work on the Code** Now you can close PyUCC and work on your code (modify files, add new ones, delete old ones). **Step C: Compare** 1. Reopen PyUCC and select the same profile. 2. Click on **🔀 Differing**. 3. This time, PyUCC detects an existing previous Baseline and asks which one to compare against (if you have multiple). 4. The result will be a table with specific color coding: * **Green:** Added files or improved metrics. * **Red:** Deleted files or worsened metrics (e.g., increased complexity). * **Yellow/Orange:** Modified files. * **Δ (Delta) Columns:** Show numerical differences (e.g., `+50` code lines, `-2` complexity). > **Diff Viewer:** If you double-click a row in the Differing results, a window will open showing the two files side-by-side, highlighting exactly which lines changed. --- ## 5. Exemplary Use Cases ### Case 1: Refactoring * **Goal:** You want to clean up code and ensure you haven't increased complexity. * **Action:** Create a Baseline before starting. Perform refactoring. Run *Differing*. * **Verification:** Check the **Δ avg_cc** column. If it is negative (e.g., `-0.5`), great! You reduced complexity. If **Δ comment_lines** is positive, you improved documentation. ### Case 2: Code Review * **Goal:** A colleague added a new feature. What changed? * **Action:** Run *Differing* against the previous master/main version. * **Verification:** Sort by "Status". Immediately see **Added** (A) and **Modified** (M) files. Open the Diff Viewer on modified files to inspect specific lines. --- ## 6. Development Philosophy (For Developers) PyUCC was built following rigorous software engineering principles, reflected in its stability and usage. ### 6.1 Clean Code & PEP8 Standards The code adheres to the Python **PEP8** standard. This ensures that if you ever want to extend the tool or write automation scripts using the `core` modules, you will find readable, standardized, and predictable code. ### 6.2 Separation of Concerns (SoC) The application is strictly divided into two parts: 1. **Core (`pyucc.core`):** Contains pure logic (scanning, metric calculation, diff algorithms). It knows nothing about the GUI. 2. **GUI (`pyucc.gui`):** Handles only visualization and user interaction. **Philosophy:** This allows changing the interface without breaking the logic, or using the logic via command line without launching the GUI. ### 6.3 Non-Blocking UI (Worker Manager) You may notice the interface never freezes, even when analyzing thousands of files. This is thanks to the **WorkerManager**. All heavy operations are executed in separate background threads. The GUI receives updates via a thread-safe `queue`. * **User Benefit:** You can always press "Cancel" if an operation takes too long. ### 6.4 Intelligent Matching Algorithm (Gale-Shapley) In *Differing*, PyUCC doesn't just check if filenames are identical. It uses an algorithm inspired by the "Stable Marriage Problem" (Gale-Shapley) combined with Levenshtein distance on paths. * **Philosophy:** If you move a file from one folder to another, the system attempts to recognize it as the *same* file moved, rather than marking one as "Deleted" and one as "Added". ### 6.5 Determinism The system uses content hashing (SHA1/MD5) to optimize calculations (caching) and to determine if a file has *truly* changed, ignoring the filesystem modification timestamp if the content remains identical. --- ## 7. Troubleshooting Common Issues * **Program finds no files:** Check the Profile Manager to see if the file extension is selected in the language list or if the folder is covered by "Ignore patterns". * **Extreme slowness:** If you included folders with thousands of small non-code files (e.g., `node_modules` or image assets), add them to "Ignore patterns". * **Empty Diff Viewer:** Ensure the source files still exist on disk. If you deleted the project folder after creating the baseline, the viewer cannot display the current file.