Jetpack Compose Convention

패키지 구조

feature:xxx
 ├─ 📁 navigation
 └─ 📁 ui
     ├─ 📁 component
     ├─ 📄 Screen
     ├─ 📄 UiEvent
     ├─ 📄 UiState
     ├─ 📄 ViewModel
     └─ ...

Bottari
 ├─ app // 앱 진입점
 ├─ build-logic // 공통 Gradle 설정, 플러그인 정의
 ├─ core
 │   ├─ core:designsystem // 색상·타이포·컴포넌트 등 공통 디자인 시스템
 │   ├─ core:ui // FadeEdge, Sheet 등 도메인 독립 UI 유틸
 │   ├─ core:model // 순수 Kotlin 데이터 클래스 정의
 │   ├─ core:domain // UseCase 등 비즈니스 로직 인터페이스
 │   ├─ core:data // Repository 구현 및 데이터 조합 계층
 │   ├─ core:network // Retrofit·OkHttp 기반 API 통신 정의
 │   └─ core:local // Room·DataStore 등 로컬 저장 구현
 └─ feature
     ├─ feature:main       // 첫 진입 + 메인 NavHost
     └─ ... (기능별 추가)

컴포넌트 분리

Screen → ScreenContent → Section(Header, Body …) → Element(Button, Image …)

규칙 1. 역할이 두 개 이상 보이면 잘라낸다 (단일 책임)

규칙 2. 동일/유사한 UI가 2번 이상 등장하면 분리 (Common or Element)

규칙 3. 중첩 깊이 기준

Column {
    // 여기 분리
    Row {
        Column {
            Row { ... }
            Text()
        }
    }
    
    Text()
}`

컴포저블 함수

Composable 함수 명명

규칙

• UI를 그리는 @Composable 함수 이름은 PascalCase + 명사형으로 작성한다.
• 반환값이 Unit이면 명사형으로, 값을 반환한다면 동사형으로 작성해도 된다.

이유

• Composable은 “UI 객체 생성자”처럼 동작하므로 명사형이 더 직관적이다.
• Kotlin 네이밍 컨벤션과 Material 라이브러리(Button, Card, Text) 스타일을 따른다.

// ✅ 올바른 예시
@Composable
fun ProfileCard(userName: String, modifier: Modifier = Modifier) {
    Text(text = userName)
}

// 🚫 잘못된 예시
@Composable
fun drawProfileCard(userName: String) { // 동사 시작 X
    Text(text = userName)
}

파라미터 순서

규칙

• 컴포저블 함수에 인자를 전달할 때 파라미터 순서를 준수한다.
  • 필수 파라미터 → Modifier → 선택적 파라미터
• 파라미터가 선언된 순서대로 전달한다.

이유

• 핵심 데이터, 레이아웃 관련 설정, UI 옵션 순서대로 작성하면 “무엇을 보여줄지, 어떻게 배치할지, 어떤 상태로 보여줄지” 라는 논리적 흐름을 표현할 수 있다.

• 순서가 통일되어야 코드의 일관성이 향상된다.

  @Composable
  fun Text(
      text: String,
      modifier: Modifier = Modifier,
      color: Color = Color.Unspecified,
      fontSize: TextUnit = TextUnit.Unspecified,
      fontStyle: FontStyle? = null,
      fontWeight: FontWeight? = null,
      fontFamily: FontFamily? = null,
      letterSpacing: TextUnit = TextUnit.Unspecified,
      textDecoration: TextDecoration? = null,
      textAlign: TextAlign? = null,
      lineHeight: TextUnit = TextUnit.Unspecified,
      overflow: TextOverflow = TextOverflow.Clip,
      softWrap: Boolean = true,
      maxLines: Int = Int.MAX_VALUE,
      minLines: Int = 1,
      onTextLayout: ((TextLayoutResult) -> Unit)? = null,
      style: TextStyle = LocalTextStyle.current
  )
  
  // ✅ 올바른 예시
  Text(
  	text = "텍스트",
  	modifier = modifier,
  	color = Color.Black,
  	maxLines = 1,
  )
  
  // 🚫 잘못된 예시
  Text(
  	color = Color.Black,
  	modifier = modifier,
  	text = "텍스트",
  	maxLines = 1,
  )

파라미터 네이밍

규칙

• 파라미터 명에 자료형을 명시하지 않는다.

이유

• Kotlin은 타입 추론 언어이기 때문에, 자료형이 명확한 경우 이름에 작성할 필요가 없다.

• Jetpack Compose는 선언형 UI를 지향하기 때문에, “무엇을 보여주는가”에 집중해야 한다.

  // ✅ 올바른 예시
  @Composable
  fun ItemEditLazyColumn(
      items: List<PersonalChecklistItemUiModel>,
      onDeleteClick: (Long) -> Unit,
      listState: LazyListState,
      modifier: Modifier = Modifier,
  )
  
  // 🚫 잘못된 예시
  @Composable
  fun ItemEditLazyColumn(
      itemList: List<PersonalChecklistItemUiModel>,
      onDeleteClick: (Long) -> Unit,
      listState: LazyListState,
      modifier: Modifier = Modifier,
  )

규칙

• 이벤트 핸들러 (람다 함수) 는 on + 주어 + 동사 형식으로 작성한다.
  • 매개변수 리스트(())가 안의 요소가 2개 이상일 때 (name: String, id: Long) -> Unit 형식으로 작성한다.
• 이벤트 핸들러가 호출되는 곳에서는 on + 동사 형식으로 작성한다. (컴포저블이 분리되어 있는 경우)

이유

• “무언가 발생했을 때 호출되는 콜백”이므로, 그 이름은 트리거되는 시점을 명확히 드러내야 한다.

• Jetpack Compose의 공식 컴포넌트는 모두 위 규칙을 따른다.

• 전달되는 로직을 실행하는 게 아니라 외부에 알리는 역할이라는 점을 명시해야 한다.

  // ✅ 올바른 예시
  @Composable
  fun RepeatDaySelector(
      alarm: AlarmUiModel,
      onRepeatDaysChange: (RepeatDayUiModel) -> Unit,
      modifier: Modifier = Modifier,
  )
  
  // 🚫 잘못된 예시 1 : 동사 + 주어 형태인 경우
  @Composable
  fun RepeatDaySelector(
      alarm: AlarmUiModel,
      onChangeRepeatDays: (RepeatDayUiModel) -> Unit,
      modifier: Modifier = Modifier,
  )
  
  // 🚫 잘못된 예시 2 : 동사가 과거형인 경우
  @Composable
  fun RepeatDaySelector(
      alarm: AlarmUiModel,
      onChangedRepeatDays: (RepeatDayUiModel) -> Unit,
      modifier: Modifier = Modifier,
  )

Modifier

Modifier 파라미터

규칙

• UI를 출력하는 모든 Composable에는 modifier: Modifier = Modifier 파라미터를 포함해야 한다.
• 위치는 필수 파라미터 뒤, 첫 번째 선택적 파라미터여야 한다.

// ✅ 올바른 예시
@Composable
fun ProfileCard(
    name: String,
    modifier: Modifier = Modifier,
) {
    Text(
        text = name,
        modifier = modifier
            .padding(8.dp)
            .background(Color.LightGray)
    )
}

// 🚫 잘못된 예시 — modifier 위치가 뒤쪽
@Composable
fun ProfileCard(
    name: String,
    backgroundColor: Color = Color.Gray,
    modifier: Modifier = Modifier,
) { ... }

State

State 호이스팅 (Hoisting)

규칙

• MutableState나 State를 직접 파라미터로 받지 않는다.

• 대신 현재 값 + 변경 콜백 형태로 받는다.

  예: (value: String, onValueChange: (String) -> Unit)

이유

• 상태 소유권이 명확해지고, ViewModel 또는 상위 컴포넌트가 재사용 가능해진다.
• Compose recomposition 이 최적화된다.

// ✅ 올바른 예시
@Composable
fun NameField(
    value: String,
    onValueChange: (String) -> Unit,
    modifier: Modifier = Modifier,
) {
    TextField(
        value = value,
        onValueChange = onValueChange,
        modifier = modifier
    )
}

// 🚫 잘못된 예시
@Composable
fun NameField(
    nameState: MutableState<String>, // 상태 직접 전달 ❌
    modifier: Modifier = Modifier,
) {
    TextField(
        value = nameState.value,
        onValueChange = { nameState.value = it },
        modifier = modifier
    )
}

기본값 관리

규칙

• 기본값은 Companion object 또는 ComponentDefaults 네임스페이스로 분리한다.
• null을 “기본값”으로 사용하지 않는다. null은 “없음”을 의미해야 한다.

이유

• 내부 로직과 기본값 정의를 분리하면 테스트와 유지보수가 쉬워진다.
• 명시적 기본값은 코드 예측 가능성을 높인다.

object CardDefaults {
    val ContainerColor = Color.White
    val Shape = RoundedCornerShape(12.dp)
}

@Composable
fun InfoCard(
    modifier: Modifier = Modifier,
    containerColor: Color = CardDefaults.ContainerColor,
    shape: Shape = CardDefaults.Shape,
    content: @Composable () -> Unit,
) {
    Surface(
        modifier = modifier,
        color = containerColor,
        shape = shape,
    ) {
        content()
    }
}

Stateless vs Stateful 구분

규칙

• 가능한 한 stateless 컴포넌트로 작성하고 상태를 외부에서 주입받도록 설계한다.

이유

• 테스트 용이성 향상
• Preview, UI Test, Snapshot Test에서 재사용 가능
• ViewModel과 명확히 분리

// ✅ Stateless
@Composable
fun Counter(
    count: Int,
    onIncrement: () -> Unit,
) {
    Button(onClick = onIncrement) {
        Text("Count: $count")
    }
}

// 🚫 Stateful — 내부에서 remember 사용 (호출자 제어 불가)
@Composable
fun Counter() {
    var count by remember { mutableStateOf(0) }
    Button(onClick = { count++ }) {
        Text("Count: $count")
    }
}

Slot API

규칙

• 하위 UI를 커스터마이징할 여지가 있다면 @Composable () -> Unit 형태의 Slot 제공.
• SlotScope (RowScope, BoxScope 등)를 함께 전달하면 더욱 유연하다.

이유

• Button, Card, Scaffold 등과 같은 구조적 컴포넌트는 슬롯이 확장성을 결정한다.

@Composable
fun AlertDialogCard(
    title: String,
    modifier: Modifier = Modifier,
    content: @Composable ColumnScope.() -> Unit,
) {
    Column(
        modifier = modifier
            .padding(16.dp)
            .background(Color.White, RoundedCornerShape(8.dp))
    ) {
        Text(text = title, style = MaterialTheme.typography.titleMedium)
        Spacer(Modifier.height(8.dp))
        content()
    }
}

접근성

규칙

• 이미지를 표현하는 컴포넌트에는 contentDescription 작성.
• 이미지가 순전히 장식용이고 클릭 가능하지 않거나 콘텐츠와 관련이 없다면 contentDescription을 null로 설정.
• 클릭 가능 요소는 Modifier.semantics 또는 Modifier.clickable 로 시맨틱 정보 포함.

이유

• 스크린 리더, 음성 안내 등 보조기기 접근성 확보를 위한 최소 조건이다.

@Composable
fun Avatar(
    imageUrl: String,
    contentDescription: String?,
    modifier: Modifier = Modifier,
) {
    Image(
        painter = rememberAsyncImagePainter(imageUrl),
        contentDescription = contentDescription,
        modifier = modifier
            .size(40.dp)
            .clip(CircleShape)
    )
}

API 변경 시 원칙

규칙

• 기존 파라미터는 절대 제거하지 않는다.
• 새 파라미터를 추가할 때는 반드시 기본값(default)을 지정한다.
• 필요 시 오버로드로 대체하고, 기존 함수는 @Deprecated 처리한다.

이유

• Compose는 함수 기반 API이므로, 파라미터 삭제가 바로 컴파일 에러로 이어진다.
• 하위 호환성을 보장해야 팀 내/외부 사용자 코드가 안전하게 유지된다.

// ✅ 새 파라미터를 추가한 버전
@Composable
fun Badge(
    count: Int,
    modifier: Modifier = Modifier,
    backgroundColor: Color = Color.Red, // 새로 추가된 파라미터
) { ... }

// 🚫 기존 함수를 바로 수정하지 않는다
@Deprecated("Use Badge(count, modifier, backgroundColor) instead",
    level = DeprecationLevel.HIDDEN)
@Composable
fun Badge(count: Int, modifier: Modifier = Modifier) =
    Badge(count, modifier, backgroundColor = Color.Red)

참고 자료

Compose API Guideline

Compose Component API Guideline

https://hongbeomi.medium.com/번역-compose-api-가이드라인-e6d999408d92