Development Conventions

Code style, naming, and documentation standards for the Bidder backend.

Gradle Build Conventions

Custom plugins in buildSrc/:

Plugin	Purpose
ru.savbros.kotlin-conventions	Base Kotlin + JVM 21
ru.savbros.application-conventions	Main app with Spring Boot
ru.savbros.service-conventions	Service modules (WebFlux, R2DBC)
ru.savbros.library-conventions	Shared libraries
ru.savbros.client-conventions	External API clients

Dependency rules:

• Application depends on *-service-impl
• *-service-impl depends on *-service-api
• Services depend on libraries and other service APIs (not implementations)

---

Naming Conventions

Element	Convention
Packages	ru.savbros.bidder.<domain>.<layer>
Domain models	Plain data classes in api/model/
DTOs	Suffix: Dto, Request, Response. Simple class names must be globally unique (see DTO naming)
Entities	Suffix: Entity
Converters	Extension functions: fun X.toY()
DAOs	Interface in dao/api/, impl in dao/impl/

DTO Naming

Never create DTO classes with the same simple name in different modules. SpringDoc uses the simple class name as the OpenAPI schema key, so two classes named AccountDto in different packages will collide — one silently shadows the other, producing incorrect Swagger documentation.

If a domain-specific DTO duplicates an existing name, prefix it with the domain context (e.g., SearchAccountDto instead of AccountDto in the campaign-search module).

---

Code Structuring

One File = One Class

Each Kotlin file contains exactly one public class/interface/object. Exception: Tightly coupled classes (e.g., sealed class with subclasses).

Service Module Structure

*-service-api/
  api/service/      # Public interfaces
  api/model/        # Domain models
  api/dto/          # Request/Response DTOs

*-service-impl/
  config/           # @Configuration classes
  controller/       # REST controllers
  converter/        # Entity <-> Model converters
  dao/api/          # DAO interfaces
  dao/impl/         # DAO implementations
  dao/entity/       # R2DBC entities
  dao/repository/   # Spring Data repositories
  scheduler/        # @Scheduled jobs
  security/         # Authorization policies
  service/          # Service implementations

Package Rules

1. Top-level packages are type-based (service/, dao/, config/)
2. Feature subpackages allowed when classes exceed comfort limits
3. Never mix feature subpackages with flat files at same level

# CORRECT
service/sync/SyncServiceImpl.kt
service/import/ImportServiceImpl.kt

# INCORRECT
service/sync/SyncServiceImpl.kt
service/SomeOtherService.kt    # BAD: flat file alongside subpackage

---

Documentation Standards

KDoc Requirements

Document:

• Interface classes (class-level)
• Methods in interfaces
• Implementation classes (class-level only)
• Data classes (single line)

Style:

• Minimalistic - state what it does
• No examples in docs
• Focus on "what", not "how"

Do NOT document:

• Method implementations
• Private methods/fields
• Deleted code references

Comments Policy

Never write inline comments except for:

• Critical bug fixes requiring explanation
• Non-obvious algorithmic logic
• Temporary workarounds with FIXME/TODO

Instead use:

• Descriptive variable/function names
• Decomposition into smaller functions
• Named constants for magic numbers

---

Kotlin Code Style

Result Handling

Use kotlin.Result<T> with expression syntax:

override suspend fun syncAll(): Result<Unit> = runCatching {
    accounts.forEach { syncAccount(it) }
}.onFailure { e ->
    logger.error(e) { "Failed: ${e.message}" }
}

Guidelines:

• Use kotlin.Result<T> (not custom types)
• Expression syntax: = runCatching { }
• Chain .onSuccess { } and .onFailure { } for side effects

Result Extraction

result.isSuccess / result.isFailure
result.getOrThrow()
result.getOrNull()
result.getOrElse { default }

---

Testing

Unit Tests

• JUnit 5 with Kotlin test
• MockK for mocking

E2E Tests

See bidder-e2e-tests/INTEGRATION_TESTING_GUIDE.md

Key conventions:

• Use runTest { } for coroutines
• Unique test data with UUID.randomUUID()
• Verify via service beans, not DAOs
• Use withContext(userFactory.createCallerContextFromAccessToken(token))