приклад code style guide

csg.md

Code Style Guide

1. Загальні принципи

• Читабельність важливіша за скорочення
• Код пишеться для людей, а не для компілятора
• Єдиний стиль у всіх шарах (API, Application, Domain, Infrastructure)
• Мінімум магії, максимум явності

---

2. Naming conventions

2.1 Загальні правила

• PascalCase — класи, record-и, enum-и, public методи
• camelCase — локальні змінні, private поля
• UPPER_SNAKE_CASE — лише для констант
• Назви мають відображати бізнес-сенс, не технічну реалізацію

2.2 Класи та файли

public class CreateAdCommand
public class AdCreatedEvent
public class PaymentService

• 1 файл = 1 public тип
• Назва файлу = назва класу

2.3 Методи

public async Task<Result<AdId>> HandleAsync(CreateAdCommand command)

• Дієслово + іменник
• Async-методи завжди з суфіксом Async

---

3. Архітектурні правила (Clean Architecture)

3.1 Заборонені залежності

• Domain ❌ Infrastructure
• Domain ❌ API
• Application ❌ API

3.2 Дозволені залежності

API -> Application -> Domain
     -> Infrastructure -> Domain

3.3 Domain rules

• Без Entity Framework
• Без HttpContext
• Без логування
• Тільки бізнес-логіка

---

4. Domain layer

4.1 Entities

public class Ad : AggregateRoot<AdId>
{
    public AdTitle Title { get; private set; }
    public Money Price { get; private set; }
}

• Приватні сеттери
• Інваріанти в конструкторі

4.2 Value Objects

public record Money(decimal Amount, string Currency);

• Immutable
• Без поведінки з побічними ефектами

---

5. Application layer

5.1 Commands / Queries

• Один use case = один handler
• Без бізнес-логіки
• Без try/catch (обробка глобально)

public sealed class CreateAdHandler : ICommandHandler<CreateAdCommand>

5.2 Result pattern

return Result.Fail(Errors.Ad.NotFound);

• Без throw для бізнес-помилок

---

6. API layer

6.1 Controllers

• Тонкі контролери
• Жодної логіки

[HttpPost]
public async Task<IActionResult> Create(CreateAdRequest request)

6.2 DTO

• DTO ≠ Domain models
• Мапінг через Mapper / Extension methods

---

7. Infrastructure layer

7.1 Repositories

public class AdRepository : IAdRepository

• EF Core тільки тут
• No business rules

7.2 External services

• Через інтерфейси
• Retry / Circuit Breaker

---

8. Error handling

• Business errors → Result
• Technical errors → Exceptions
• Єдиний middleware для помилок

---

9. Logging

• Serilog
• CorrelationId у кожному запиті
• Без логування персональних даних

---

10. Formatting

• var дозволено, якщо тип очевидний
• Максимум 120 символів у рядку
• Порожній рядок між логічними блоками

---

11. Testing style

11.1 Unit tests

• AAA pattern
• Назви тестів: Method_WhenCondition_ShouldResult

11.2 Integration tests

• Testcontainers
• Реальна база

---

12. Заборонено

• Static state
• God classes
• Anemic domain
• Catch(Exception)

---

13. Автоматизація

• EditorConfig
• StyleCop
• Roslyn Analyzers
• CI: build fails on style violations

---

14. Definition of Done (Code)

• Code style дотримано
• Покрито тестами
• No warnings
• Reviewed