Common Codes

IMPORTANT: All enums that represent categorized business codes must implement CommonCode. This approach ensures consistent code/description access across the project and enables automatic REST Docs generation via CommonCodeDocsTest.

Enum definition

Standard pattern

import io.glory.common.codes.CommonCode

enum class OrderStatus(
    override val description: String,
) : CommonCode {
    PENDING("Order placed, awaiting payment"),
    PAID("Payment confirmed"),
    SHIPPED("Order shipped"),
    DELIVERED("Order delivered"),
    CANCELLED("Order cancelled"),
    REFUNDED("Order refunded"),
    ;
}

Naming conventions

Trailing semicolon

IMPORTANT: Add a trailing semicolon (;) after the last enum constant when the enum has a body (companion object, methods, or properties).

// Good: Trailing semicolon before companion object
enum class UserRole(
    override val description: String,
) : CommonCode {
    ADMIN("System administrator"),
    USER("Regular user"),
    GUEST("Guest user"),
    ;  // Required when enum has a body

    companion object { ... }
}

// Bad: Missing semicolon
enum class UserRole(...) : CommonCode {
    ADMIN("System administrator"),
    GUEST("Guest user")  // Compilation error if companion follows
    companion object { ... }
}

JPA entity usage

IMPORTANT: Use @Enumerated(EnumType.STRING) for enum fields in JPA entities. Never use EnumType.ORDINAL — it breaks silently when you reorder or remove enum constants.

Correct: EnumType.STRING

@Entity
@Table(name = "orders")
class Order(
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    val id: Long = 0,

    @Enumerated(EnumType.STRING)
    @Column(nullable = false, length = 20)
    var status: OrderStatus = OrderStatus.PENDING,
) : BaseTimeEntity()

Incorrect: EnumType.ORDINAL

// Bad: ORDINAL stores position index — breaks when enum order changes
@Enumerated(EnumType.ORDINAL)
@Column(nullable = false)
var status: OrderStatus = OrderStatus.PENDING
// DB stores: 0, 1, 2... If PENDING moves to position 2, all data corrupts

Column length

Set @Column(length = N) to match the longest enum constant name. This setting prevents truncation and documents the expected range.

// Good: length matches longest constant ("CANCELLED" = 9 chars, use 20 for safety)
@Enumerated(EnumType.STRING)
@Column(nullable = false, length = 20)
var status: OrderStatus = OrderStatus.PENDING

// Bad: No length specified — defaults to 255, wastes storage
@Enumerated(EnumType.STRING)
@Column(nullable = false)
var status: OrderStatus = OrderStatus.PENDING

Lookup methods

fromName factory

Provide a fromName companion method when external systems send name values that must be mapped to enum constants.

companion object {
    fun fromName(name: String): PaymentMethod =
        entries.find { it.name == name }
            ?: throw IllegalArgumentException("Unknown PaymentMethod: $name")
}

Nullable lookup

Use a nullable variant when the name may not exist and null is an acceptable result.

companion object {
    fun fromNameOrNull(name: String): PaymentMethod? =
        entries.find { it.name == name }
}

When to use CommonCode

When not to implement CommonCode

Do not implement CommonCode for:

• Response codes — Use ResponseCode (e.g., ErrorCode and SuccessCode)
• Internal flags — Simple enums without description that are never exposed externally
• Sealed classes — Use sealed classes for complex state with data

// Good: ResponseCode for HTTP response codes (not CommonCode)
enum class ErrorCode(
    override val status: Int,
    override val message: String,
) : ResponseCode {
    DATA_NOT_FOUND(406, "Data not found"),
}

// Good: Simple enum without CommonCode (internal use only)
enum class SortDirection {
    ASC, DESC
}

Package location

REST Docs integration

CommonCodeDocsTest automatically documents enums implementing CommonCode. The test generates REST Docs snippets listing all name and description pairs, ensuring API documentation stays in sync with the codebase.

Common pitfalls

Summary checklist

Before submitting code with enums, verify:

• All categorized domain codes implement CommonCode
• Enum has description property
• JPA entity fields use @Enumerated(EnumType.STRING) — never ORDINAL
• @Column(length = N) is set to a reasonable value for enum fields
• Trailing semicolon is present after the last constant when the enum has a body
• fromName companion method exists when external name mapping is needed
• Enum is placed in the correct package (domain/{feature}/entity/ or domain/common/codes/)
• Response codes use ResponseCode, not CommonCode