mumucc 0.4.4 → 0.4.10

package/defaults/plugin-seed/marketplaces/claude-code-workflows/plugins/conductor/templates/code_styleguides/csharp.md

@@ -0,0 +1,600 @@
+# C# Style Guide
+
+C# conventions and best practices for .NET development.
+
+## Naming Conventions
+
+### General Rules
+
+```csharp
+// PascalCase for public members, types, namespaces
+public class UserService { }
+public void ProcessOrder() { }
+public string FirstName { get; set; }
+
+// camelCase for private fields, parameters, locals
+private readonly ILogger _logger;
+private int _itemCount;
+public void DoWork(string inputValue) { }
+
+// Prefix interfaces with I
+public interface IUserRepository { }
+public interface INotificationService { }
+
+// Suffix async methods with Async
+public async Task<User> GetUserAsync(int id) { }
+public async Task ProcessOrderAsync(Order order) { }
+
+// Constants: PascalCase (not SCREAMING_CASE)
+public const int MaxRetryCount = 3;
+public const string DefaultCurrency = "USD";
+```
+
+### Field and Property Naming
+
+```csharp
+public class Order
+{
+    // Private fields: underscore prefix + camelCase
+    private readonly IOrderRepository _repository;
+    private int _itemCount;
+
+    // Public properties: PascalCase
+    public int Id { get; set; }
+    public string CustomerName { get; set; }
+    public DateTime CreatedAt { get; init; }
+
+    // Boolean properties: Is/Has/Can prefix
+    public bool IsActive { get; set; }
+    public bool HasDiscount { get; set; }
+    public bool CanEdit { get; }
+}
+```
+
+## Async/Await Patterns
+
+### Basic Async Usage
+
+```csharp
+// Always use async/await for I/O operations
+public async Task<User> GetUserAsync(int id)
+{
+    var user = await _repository.FindAsync(id);
+    if (user == null)
+    {
+        throw new NotFoundException($"User {id} not found");
+    }
+    return user;
+}
+
+// Don't block on async code
+// Bad
+var user = GetUserAsync(id).Result;
+
+// Good
+var user = await GetUserAsync(id);
+```
+
+### Async Best Practices
+
+```csharp
+// Use ConfigureAwait(false) in library code
+public async Task<Data> FetchDataAsync()
+{
+    var response = await _httpClient.GetAsync(url)
+        .ConfigureAwait(false);
+    return await response.Content.ReadAsAsync<Data>()
+        .ConfigureAwait(false);
+}
+
+// Avoid async void except for event handlers
+// Bad
+public async void ProcessOrder() { }
+
+// Good
+public async Task ProcessOrderAsync() { }
+
+// Event handler exception
+private async void Button_Click(object sender, EventArgs e)
+{
+    try
+    {
+        await ProcessOrderAsync();
+    }
+    catch (Exception ex)
+    {
+        HandleError(ex);
+    }
+}
+```
+
+### Parallel Async Operations
+
+```csharp
+// Execute independent operations in parallel
+public async Task<DashboardData> LoadDashboardAsync()
+{
+    var usersTask = _userService.GetActiveUsersAsync();
+    var ordersTask = _orderService.GetRecentOrdersAsync();
+    var statsTask = _statsService.GetDailyStatsAsync();
+
+    await Task.WhenAll(usersTask, ordersTask, statsTask);
+
+    return new DashboardData
+    {
+        Users = await usersTask,
+        Orders = await ordersTask,
+        Stats = await statsTask
+    };
+}
+
+// Use SemaphoreSlim for throttling
+public async Task ProcessItemsAsync(IEnumerable<Item> items)
+{
+    using var semaphore = new SemaphoreSlim(10); // Max 10 concurrent
+
+    var tasks = items.Select(async item =>
+    {
+        await semaphore.WaitAsync();
+        try
+        {
+            await ProcessItemAsync(item);
+        }
+        finally
+        {
+            semaphore.Release();
+        }
+    });
+
+    await Task.WhenAll(tasks);
+}
+```
+
+## LINQ
+
+### Query Syntax vs Method Syntax
+
+```csharp
+// Method syntax (preferred for simple queries)
+var activeUsers = users
+    .Where(u => u.IsActive)
+    .OrderBy(u => u.Name)
+    .ToList();
+
+// Query syntax (for complex queries with joins)
+var orderSummary =
+    from order in orders
+    join customer in customers on order.CustomerId equals customer.Id
+    where order.Total > 100
+    group order by customer.Name into g
+    select new { Customer = g.Key, Total = g.Sum(o => o.Total) };
+```
+
+### LINQ Best Practices
+
+```csharp
+// Use appropriate methods
+var hasItems = items.Any();                    // Not: items.Count() > 0
+var firstOrDefault = items.FirstOrDefault();  // Not: items.First()
+var count = items.Count;                       // Property, not Count()
+
+// Avoid multiple enumerations
+// Bad
+if (items.Any())
+{
+    foreach (var item in items) { }
+}
+
+// Good
+var itemList = items.ToList();
+if (itemList.Count > 0)
+{
+    foreach (var item in itemList) { }
+}
+
+// Project early to reduce memory
+var names = users
+    .Where(u => u.IsActive)
+    .Select(u => u.Name)  // Select only what you need
+    .ToList();
+```
+
+### Common LINQ Operations
+
+```csharp
+// Filtering
+var adults = people.Where(p => p.Age >= 18);
+
+// Transformation
+var names = people.Select(p => $"{p.FirstName} {p.LastName}");
+
+// Aggregation
+var total = orders.Sum(o => o.Amount);
+var average = scores.Average();
+var max = values.Max();
+
+// Grouping
+var byDepartment = employees
+    .GroupBy(e => e.Department)
+    .Select(g => new { Department = g.Key, Count = g.Count() });
+
+// Joining
+var result = orders
+    .Join(customers,
+        o => o.CustomerId,
+        c => c.Id,
+        (o, c) => new { Order = o, Customer = c });
+
+// Flattening
+var allOrders = customers.SelectMany(c => c.Orders);
+```
+
+## Dependency Injection
+
+### Service Registration
+
+```csharp
+// In Program.cs or Startup.cs
+public void ConfigureServices(IServiceCollection services)
+{
+    // Transient: new instance each time
+    services.AddTransient<IEmailService, EmailService>();
+
+    // Scoped: one instance per request
+    services.AddScoped<IUserRepository, UserRepository>();
+
+    // Singleton: one instance for app lifetime
+    services.AddSingleton<ICacheService, MemoryCacheService>();
+
+    // Factory registration
+    services.AddScoped<IDbConnection>(sp =>
+    {
+        var config = sp.GetRequiredService<IConfiguration>();
+        return new SqlConnection(config.GetConnectionString("Default"));
+    });
+}
+```
+
+### Constructor Injection
+
+```csharp
+public class OrderService : IOrderService
+{
+    private readonly IOrderRepository _repository;
+    private readonly ILogger<OrderService> _logger;
+    private readonly IEmailService _emailService;
+
+    public OrderService(
+        IOrderRepository repository,
+        ILogger<OrderService> logger,
+        IEmailService emailService)
+    {
+        _repository = repository ?? throw new ArgumentNullException(nameof(repository));
+        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
+        _emailService = emailService ?? throw new ArgumentNullException(nameof(emailService));
+    }
+
+    public async Task<Order> CreateOrderAsync(OrderRequest request)
+    {
+        _logger.LogInformation("Creating order for customer {CustomerId}", request.CustomerId);
+
+        var order = new Order(request);
+        await _repository.SaveAsync(order);
+        await _emailService.SendOrderConfirmationAsync(order);
+
+        return order;
+    }
+}
+```
+
+### Options Pattern
+
+```csharp
+// Configuration class
+public class EmailSettings
+{
+    public string SmtpServer { get; set; }
+    public int Port { get; set; }
+    public string FromAddress { get; set; }
+}
+
+// Registration
+services.Configure<EmailSettings>(
+    configuration.GetSection("Email"));
+
+// Usage
+public class EmailService
+{
+    private readonly EmailSettings _settings;
+
+    public EmailService(IOptions<EmailSettings> options)
+    {
+        _settings = options.Value;
+    }
+}
+```
+
+## Testing
+
+### xUnit Basics
+
+```csharp
+public class CalculatorTests
+{
+    [Fact]
+    public void Add_TwoPositiveNumbers_ReturnsSum()
+    {
+        // Arrange
+        var calculator = new Calculator();
+
+        // Act
+        var result = calculator.Add(2, 3);
+
+        // Assert
+        Assert.Equal(5, result);
+    }
+
+    [Theory]
+    [InlineData(1, 1, 2)]
+    [InlineData(0, 0, 0)]
+    [InlineData(-1, 1, 0)]
+    public void Add_VariousNumbers_ReturnsCorrectSum(int a, int b, int expected)
+    {
+        var calculator = new Calculator();
+        Assert.Equal(expected, calculator.Add(a, b));
+    }
+}
+```
+
+### Mocking with Moq
+
+```csharp
+public class OrderServiceTests
+{
+    private readonly Mock<IOrderRepository> _mockRepository;
+    private readonly Mock<ILogger<OrderService>> _mockLogger;
+    private readonly OrderService _service;
+
+    public OrderServiceTests()
+    {
+        _mockRepository = new Mock<IOrderRepository>();
+        _mockLogger = new Mock<ILogger<OrderService>>();
+        _service = new OrderService(_mockRepository.Object, _mockLogger.Object);
+    }
+
+    [Fact]
+    public async Task GetOrderAsync_ExistingOrder_ReturnsOrder()
+    {
+        // Arrange
+        var expectedOrder = new Order { Id = 1, Total = 100m };
+        _mockRepository
+            .Setup(r => r.FindAsync(1))
+            .ReturnsAsync(expectedOrder);
+
+        // Act
+        var result = await _service.GetOrderAsync(1);
+
+        // Assert
+        Assert.Equal(expectedOrder.Id, result.Id);
+        _mockRepository.Verify(r => r.FindAsync(1), Times.Once);
+    }
+
+    [Fact]
+    public async Task GetOrderAsync_NonExistingOrder_ThrowsNotFoundException()
+    {
+        // Arrange
+        _mockRepository
+            .Setup(r => r.FindAsync(999))
+            .ReturnsAsync((Order)null);
+
+        // Act & Assert
+        await Assert.ThrowsAsync<NotFoundException>(
+            () => _service.GetOrderAsync(999));
+    }
+}
+```
+
+### Integration Testing
+
+```csharp
+public class ApiIntegrationTests : IClassFixture<WebApplicationFactory<Program>>
+{
+    private readonly HttpClient _client;
+
+    public ApiIntegrationTests(WebApplicationFactory<Program> factory)
+    {
+        _client = factory.CreateClient();
+    }
+
+    [Fact]
+    public async Task GetUsers_ReturnsSuccessAndCorrectContentType()
+    {
+        // Act
+        var response = await _client.GetAsync("/api/users");
+
+        // Assert
+        response.EnsureSuccessStatusCode();
+        Assert.Equal("application/json; charset=utf-8",
+            response.Content.Headers.ContentType.ToString());
+    }
+}
+```
+
+## Common Patterns
+
+### Null Handling
+
+```csharp
+// Null-conditional operators
+var length = customer?.Address?.Street?.Length;
+var name = user?.Name ?? "Unknown";
+
+// Null-coalescing assignment
+list ??= new List<Item>();
+
+// Pattern matching for null checks
+if (user is not null)
+{
+    ProcessUser(user);
+}
+
+// Guard clauses
+public void ProcessOrder(Order order)
+{
+    ArgumentNullException.ThrowIfNull(order);
+
+    if (order.Items.Count == 0)
+    {
+        throw new ArgumentException("Order must have items", nameof(order));
+    }
+
+    // Process...
+}
+```
+
+### Records and Init-Only Properties
+
+```csharp
+// Record for immutable data
+public record User(int Id, string Name, string Email);
+
+// Record with additional members
+public record Order
+{
+    public int Id { get; init; }
+    public string CustomerName { get; init; }
+    public decimal Total { get; init; }
+
+    public bool IsHighValue => Total > 1000;
+}
+
+// Record mutation via with expression
+var updatedUser = user with { Name = "New Name" };
+```
+
+### Pattern Matching
+
+```csharp
+// Type patterns
+public decimal CalculateDiscount(object customer) => customer switch
+{
+    PremiumCustomer p => p.PurchaseTotal * 0.2m,
+    RegularCustomer r when r.YearsActive > 5 => r.PurchaseTotal * 0.1m,
+    RegularCustomer r => r.PurchaseTotal * 0.05m,
+    null => 0m,
+    _ => throw new ArgumentException("Unknown customer type")
+};
+
+// Property patterns
+public string GetShippingOption(Order order) => order switch
+{
+    { Total: > 100, IsPriority: true } => "Express",
+    { Total: > 100 } => "Standard",
+    { IsPriority: true } => "Priority",
+    _ => "Economy"
+};
+
+// List patterns (C# 11)
+public bool IsValidSequence(int[] numbers) => numbers switch
+{
+    [1, 2, 3] => true,
+    [1, .., 3] => true,
+    [_, _, ..] => numbers.Length >= 2,
+    _ => false
+};
+```
+
+### Disposable Pattern
+
+```csharp
+public class ResourceManager : IDisposable
+{
+    private bool _disposed;
+    private readonly FileStream _stream;
+
+    public ResourceManager(string path)
+    {
+        _stream = File.OpenRead(path);
+    }
+
+    public void DoWork()
+    {
+        ObjectDisposedException.ThrowIf(_disposed, this);
+        // Work with _stream
+    }
+
+    public void Dispose()
+    {
+        Dispose(true);
+        GC.SuppressFinalize(this);
+    }
+
+    protected virtual void Dispose(bool disposing)
+    {
+        if (_disposed) return;
+
+        if (disposing)
+        {
+            _stream?.Dispose();
+        }
+
+        _disposed = true;
+    }
+}
+
+// Using statement
+using var manager = new ResourceManager("file.txt");
+manager.DoWork();
+```
+
+## Code Organization
+
+### File Structure
+
+```csharp
+// One type per file (generally)
+// Filename matches type name: UserService.cs
+
+// Order of members
+public class UserService
+{
+    // 1. Constants
+    private const int MaxRetries = 3;
+
+    // 2. Static fields
+    private static readonly object _lock = new();
+
+    // 3. Instance fields
+    private readonly IUserRepository _repository;
+
+    // 4. Constructors
+    public UserService(IUserRepository repository)
+    {
+        _repository = repository;
+    }
+
+    // 5. Properties
+    public int TotalUsers { get; private set; }
+
+    // 6. Public methods
+    public async Task<User> GetUserAsync(int id) { }
+
+    // 7. Private methods
+    private void ValidateUser(User user) { }
+}
+```
+
+### Project Structure
+
+```
+Solution/
+├── src/
+│   ├── MyApp.Api/              # Web API project
+│   ├── MyApp.Core/             # Domain/business logic
+│   ├── MyApp.Infrastructure/   # Data access, external services
+│   └── MyApp.Shared/           # Shared utilities
+├── tests/
+│   ├── MyApp.UnitTests/
+│   └── MyApp.IntegrationTests/
+└── MyApp.sln
+```