Refactor codebase for better self-documentation#2
Conversation
…rnization This refactor dramatically improves code clarity, maintainability, and self-documentation by eliminating boilerplate, removing redundancy, and restructuring logic for transparency. ### New Utility Classes - **Guard.cs**: Centralized parameter validation eliminating 30+ lines of boilerplate - **GitHelper.cs**: Unified Git repository detection (eliminates 2 duplicate implementations) ### New Service Classes (Extracted from Program.cs) - **AppConfig.cs**: Application configuration record (moved to Configuration/) - **ConfigLoader.cs**: JSON configuration loading with error handling - **OutputFormatter.cs**: File output with multiple format support - **StatsCalculator.cs**: Processing statistics calculation - **PathResolver.cs**: Path validation and user input handling - **ContentBuilder.cs**: Project content assembly orchestration ### Code Improvements - **Program.cs**: Reduced from 268 to 71 lines (-73%) with pure DI orchestration - **ProjectScanner.cs**: Uses Guard and GitHelper, improved naming (path → projectPath) - **FileFilterService.cs**: Uses Guard and GitHelper, removed duplicate FindGitRepoRoot - **FileUtilities.cs**: Uses Guard for validation ### Deleted Deprecated Classes - Removed MyAppsContext.cs (obsolete facade) - Removed FileChecker.cs (obsolete facade) - Removed FileUtils.cs (obsolete facade) ### Self-Documentation Improvements - Consistent parameter naming (projectPath vs path/rootPath) - Clear variable names (structure, fileContents vs sb, results) - Expressive method extraction (single responsibility) - Pure dependency injection (no static facades) - Obvious data flow through constructor injection ### Impact - 8 new focused classes with single responsibilities - Eliminated all validation boilerplate through Guard - Removed all code duplication (Git helpers, validation) - Program.cs is now pure orchestration (73% reduction) - Clear, testable, maintainable architecture - Zero functional changes - backward compatible
There was a problem hiding this comment.
Pull request overview
This PR performs a comprehensive refactoring to improve code clarity and maintainability by extracting functionality from a monolithic Program.cs into focused, single-responsibility service classes and utility helpers. The refactor introduces a Guard utility class for centralized parameter validation, eliminates code duplication (particularly Git repository detection logic), and establishes consistent dependency injection patterns throughout the codebase.
Key Changes
- Extracted 8 new focused classes from Program.cs, reducing it from 268 to 71 lines (-73%)
- Introduced Guard utility class to centralize parameter validation and reduce boilerplate
- Unified Git repository detection logic in GitHelper, eliminating duplicate implementations
- Improved variable and parameter naming for better self-documentation (projectPath, structure, fileContents)
Reviewed changes
Copilot reviewed 15 out of 15 changed files in this pull request and generated 10 comments.
Show a summary per file
| File | Description |
|---|---|
| Utils/Guard.cs | New centralized parameter validation utility with null checks, directory/file existence validation |
| Utils/GitHelper.cs | New unified Git repository detection helper to eliminate duplication |
| Utils/FileUtilities.cs | Refactored to use Guard for validation, removed inline comments |
| Services/StatsCalculator.cs | Extracted statistics calculation logic from Program.cs |
| Services/PathResolver.cs | Extracted path resolution and validation logic from Program.cs |
| Services/OutputFormatter.cs | Extracted output file writing and formatting logic from Program.cs |
| Services/ContentBuilder.cs | Extracted content building orchestration from Program.cs |
| Services/ConfigLoader.cs | Extracted configuration loading logic from Program.cs |
| Services/ProjectScanner.cs | Refactored to use Guard and GitHelper, improved parameter naming, removed duplicate FindGitRepoRoot |
| Services/FileFilterService.cs | Refactored to use Guard and GitHelper, removed duplicate Git detection methods |
| Program.cs | Dramatically simplified to pure DI orchestration and high-level flow control |
| Configuration/AppConfig.cs | Configuration record moved from Program.cs to dedicated file |
| MyAppsContext.cs | Deleted obsolete facade class |
| FileUtils.cs | Deleted obsolete facade class |
| FileChecker.cs | Deleted obsolete facade class |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| public ContentBuilder(ProjectScanner scanner) | ||
| { | ||
| _scanner = scanner; |
There was a problem hiding this comment.
Constructor parameter validation is missing. Both scanner and config parameters should be validated using Guard.NotNull() to maintain consistency with other service classes and prevent potential null reference exceptions.
| public OutputFormatter(IConsoleWriter console) | ||
| { | ||
| _console = console; |
There was a problem hiding this comment.
Constructor parameter validation is missing. The console parameter should be validated using Guard.NotNull() to maintain consistency with other service classes like ProjectScanner and FileFilterService.
| private readonly IConsoleWriter _console; | ||
|
|
||
| public ConfigLoader(IConsoleWriter console) | ||
| { |
There was a problem hiding this comment.
Constructor parameter validation is missing. The console parameter should be validated using Guard.NotNull() to maintain consistency with other service classes like ProjectScanner and FileFilterService.
| { | |
| { | |
| Guard.NotNull(console, nameof(console)); |
| public string Build(string projectPath, AppConfig config) | ||
| { | ||
| var content = new StringBuilder(); |
There was a problem hiding this comment.
Missing parameter validation for config. The method should validate that config is not null using Guard.NotNull() before using it to avoid potential null reference exceptions.
| } | ||
| catch (Exception) | ||
| catch | ||
| { |
There was a problem hiding this comment.
[nitpick] Removed explanatory comment provides valuable context for exception handling behavior. Consider keeping the comment: // If we can't read the file (permissions, etc.), assume it's not binary as it documents the intentional behavior of returning false on any exception.
| { | |
| { | |
| // If we can't read the file (permissions, etc.), assume it's not binary |
| @@ -33,17 +30,15 @@ public static bool IsBinaryFile(string filePath, int chunkSize = 4096, double bi | |||
| return false; | |||
| } | |||
|
|
|||
There was a problem hiding this comment.
[nitpick] Removed explanatory comment provides valuable context for exception handling behavior. Consider keeping the comment: // Check for UTF-8 BOM as it documents what the HasUtf8Bom method checks for, improving code readability.
| // Check for UTF-8 BOM |
| } | ||
| catch (Exception) | ||
| catch | ||
| { |
There was a problem hiding this comment.
[nitpick] Removed explanatory comment provides valuable context for exception handling behavior. Consider keeping the comment: // If we can't read the file, assume it's not generated code as it documents the intentional behavior of returning false on any exception.
| { | |
| { | |
| // If we can't read the file, assume it's not generated code |
| @@ -0,0 +1,34 @@ | |||
| using System.Text.Json; | |||
| using CodeContext.Configuration; | |||
There was a problem hiding this comment.
Missing using directive for CodeContext.Interfaces namespace. The IConsoleWriter interface is used but not imported, which will cause compilation errors.
| using CodeContext.Configuration; | |
| using CodeContext.Configuration; | |
| using CodeContext.Interfaces; |
|
|
||
| public PathResolver(IConsoleWriter console) | ||
| { | ||
| _console = console; |
There was a problem hiding this comment.
Constructor parameter validation is missing. The console parameter should be validated using Guard.NotNull() to maintain consistency with other service classes like ProjectScanner and FileFilterService.
| _console = console; | |
| _console = Guard.NotNull(console, nameof(console)); |
…rnization
This refactor dramatically improves code clarity, maintainability, and self-documentation by eliminating boilerplate, removing redundancy, and restructuring logic for transparency.
New Utility Classes
New Service Classes (Extracted from Program.cs)
Code Improvements
Deleted Deprecated Classes
Self-Documentation Improvements
Impact