📘 C# WinForms Coding Standards & Best Practices

Comprehensive coding standards and best practices for building maintainable, scalable C# WinForms applications. Optimized for both human developers and AI assistants (Claude Code).

---

🎯 What's This?

This repository contains coding standards, architectural guidelines, and best practices for C# WinForms development. It's designed to:

• ✅ Ensure code consistency across team members
• ✅ Provide clear guidelines for architectural decisions (MVP, MVVM, etc.)
• ✅ Help AI assistants (like Claude Code) write better WinForms code
• ✅ Serve as reference documentation for common patterns
• ✅ Include code examples and templates for quick start

---

🚀 Quick Start

📘 USAGE GUIDE - Start Here! ⭐

New to this repository? Check out the Usage Guide with practical, step-by-step examples:

• 📝 Creating a Login Form from scratch
• 📝 Creating a Customer Management Form
• 📝 Adding validation to existing forms
• 📝 Refactoring to MVP pattern
• 📝 Setting up Dependency Injection
• 📝 And more real-world scenarios!

⚡ Productivity Tools - Speed Up Development

Boost your productivity with our automation tools:

• Code Snippets 🎨

  • 7 ready-to-use snippets for Visual Studio & VS Code
  • Generate complete MVP forms in 10 seconds
  • Shortcuts: mvpform, mvpservice, asyncevent, invokeui
  • Installation Guide

• Pre-commit Hooks 🔒

  • Automatic quality checks before commits
  • Prevents broken builds, failing tests, debug code
  • 9 automated validations
  • Setup Instructions

• Project Init Scripts 🚀

  • Create new projects in 2 minutes (vs 30-60 min manual)
  • Pre-configured with DI, EF Core, Serilog, tests
  • Command: .\scripts\init-project.ps1 -ProjectName "MyApp"
  • Usage Guide

For Developers

1. Start with practical examples: USAGE_GUIDE.md ⭐
2. Install productivity tools: Snippets + Hooks + Scripts
3. Read the overview: docs/00-overview.md
4. Understand architecture: MVP Pattern
5. Follow conventions: Naming Conventions
6. Review examples: Code Examples and Example Project

For AI Assistants (Claude Code)

The CLAUDE.md file is automatically loaded by Claude Code and contains:

• Quick reference for coding standards
• Links to detailed documentation
• Pre-commit checklist
• AI-specific rules

---

📚 Documentation Structure

/winforms-coding-standards
├── CLAUDE.md                  # Auto-loaded by Claude Code
├── README.md                  # This file
├── LICENSE                    # MIT License
├── USAGE_GUIDE.md             # ⭐ Practical step-by-step examples
├── TROUBLESHOOTING.md         # 🔧 Common issues & solutions (30+ problems)
│
├── /snippets/                 # ⚡ Code snippets for rapid development
│   ├── /visual-studio/        # VS .snippet files
│   ├── /vscode/               # VS Code JSON snippets
│   └── README.md              # Installation guide
│
├── /.githooks/                # 🔒 Pre-commit quality checks
│   ├── pre-commit             # Main hook script
│   ├── install.sh             # Installation script
│   └── README.md              # Hook documentation
│
├── /scripts/                  # 🚀 Project automation scripts
│   ├── init-project.ps1       # PowerShell (Windows)
│   ├── init-project.sh        # Bash (Linux/Mac)
│   └── README.md              # Usage guide
│
├── /docs/
│   ├── 00-overview.md         # Complete documentation index
│   │
│   ├── /architecture/         # Architecture patterns & design
│   │   ├── project-structure.md
│   │   ├── mvp-pattern.md
│   │   ├── mvvm-pattern.md
│   │   └── dependency-injection.md
│   │
│   ├── /conventions/          # Coding conventions
│   │   ├── naming-conventions.md
│   │   ├── code-style.md
│   │   └── comments-docstrings.md
│   │
│   ├── /ui-ux/               # UI & UX best practices
│   │   ├── responsive-design.md
│   │   ├── form-communication.md
│   │   ├── data-binding.md
│   │   ├── input-validation.md
│   │   └── datagridview-practices.md
│   │
│   ├── /best-practices/      # General best practices
│   │   ├── async-await.md
│   │   ├── resource-management.md
│   │   ├── error-handling.md
│   │   ├── thread-safety.md
│   │   ├── performance.md
│   │   ├── security.md
│   │   └── configuration.md
│   │
│   ├── /testing/             # Testing guidelines
│   │   ├── testing-overview.md
│   │   ├── unit-testing.md
│   │   ├── integration-testing.md
│   │   └── ui-testing.md
│   │
│   ├── /advanced/            # Advanced topics
│   │   ├── nullable-reference-types.md
│   │   ├── linq-practices.md
│   │   └── localization-i18n.md
│   │
│   ├── /deployment/          # Deployment & packaging
│   │   └── packaging.md
│   │
│   └── /examples/            # Working code examples
│       ├── mvp-example.md
│       ├── di-example.md
│       └── async-ui-example.md
│
├── /.claude/
│   └── /commands/            # Claude Code slash commands
│       ├── create-form.md
│       ├── review-code.md
│       └── add-test.md
│
└── /templates/               # Code templates
    ├── form-template.cs
    ├── service-template.cs
    ├── repository-template.cs
    └── test-template.cs

---

📖 Key Topics

Architecture

• Project Structure - Standard folder organization
• MVP Pattern - Recommended for WinForms ⭐
• MVVM Pattern - For .NET 8+ with data binding
• Dependency Injection - Loose coupling

Best Practices

• Async/Await - Non-blocking UI operations
• Resource Management - Prevent memory leaks
• Error Handling - Logging and exception handling
• Thread Safety - Cross-thread UI updates
• Performance - Optimization techniques
• Security - Secure coding practices

UI & UX

• Responsive Design - Adaptive layouts
• Data Binding - BindingSource pattern
• Input Validation - ErrorProvider usage
• DataGridView - Advanced grid techniques

Testing

• Testing Overview - Testing strategy
• Unit Testing - xUnit with Services
• Integration Testing - Database testing
• UI Testing - FlaUI automation

---

💡 Core Principles

1. Separation of Concerns

UI (Forms) → Presenter/ViewModel → Service → Repository → Database

• ✅ Forms handle UI only (no business logic)
• ✅ Services contain business logic
• ✅ Repositories handle data access

2. Modern C# Features

• Use async/await for all I/O operations
• Enable nullable reference types (C# 8.0+)
• Use pattern matching where appropriate
• Leverage LINQ for data manipulation

3. Resource Management

• Always dispose IDisposable resources
• Use using statements or using declarations
• Handle unmanaged resources properly

4. Testing

• Unit tests for Services (business logic)
• Integration tests for Repositories (data access)
• UI tests for critical user flows (optional)
• Aim for 80%+ code coverage

---

🎓 Learning Path

Beginner

1. Project Structure - Understand folder organization
2. Naming Conventions - Learn naming rules
3. Code Style - Follow style guidelines

Intermediate

4. MVP Pattern - Master architecture pattern
5. Async/Await - Non-blocking operations
6. Data Binding - BindingSource usage
7. Unit Testing - Write effective tests

Advanced

8. Thread Safety - Multi-threaded UI
9. Performance Optimization - Profiling & tuning
10. Localization - Multi-language support

---

🛠️ Tools & Technologies

• .NET 8.0 / .NET Framework 4.8
• C# 12.0 / C# 10.0
• Entity Framework Core 8.0
• xUnit / NUnit for testing
• Serilog / NLog for logging
• Microsoft.Extensions.DependencyInjection for DI
• FlaUI for UI automation testing (optional)

---

🤝 Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/new-guideline)
3. Add or update documentation
4. Ensure examples are tested and working
5. Submit a pull request

Guidelines for Contributors

• Keep documentation concise (200-500 lines per file)
• Include code examples with explanations
• Use markdown best practices (headings, lists, code blocks)
• Cross-reference related topics with links
• Test all code examples before committing

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Microsoft's C# Coding Conventions
• .NET Framework Design Guidelines
• Community best practices from WinForms developers

---

📞 Support & Getting Help

Having Issues?

1. Check TROUBLESHOOTING.md first - 30+ common problems solved

   • Setup & Configuration
   • Dependency Injection errors
   • Threading issues
   • Entity Framework problems
   • Performance optimization
   • Claude Code specific issues

2. Search Documentation:

   • Complete Overview
   • Usage Guide with Examples
   • Example Project

3. Ask Claude Code:

   /review-code YourFile.cs     # Check for issues
   /check-standards YourFile.cs # Validate against standards
   

4. Still Stuck?

   • Open a GitHub Issue with error details
   • Include what you've tried
   • Provide minimal code to reproduce

Other Resources

• Documentation Issues: Open an issue on GitHub
• AI Assistant Guide: See CLAUDE.md
• Contributing: See guidelines above

---

Last Updated: 2025-11-07 Version: 2.0 (Modular structure)