[Effective Kotlin] 아이템 31. 문서로 규약을 정의하라

Jimin Lim·2023년 8월 27일

effective kotlin

Effective Kotlin

목록 보기

31/39

아이템 31

문서로 규약을 정의하라

KDoc

showMessage처럼 추상화된 함수명을 사용한다면 토스트가 아니라 다른 타입으로 메시지를 노출한다고 생각할 수 있다. 따라서 함수가 무엇을 하는지 명확하게 설명하고 싶다면 KDoc 주석을 붙여주는 것이 좋다. '

KDoc 형식

/**로 시작해 */로 끝나는 형식이다. 사이 줄은 *로 시작한다.

주석의 구조는 다음과 같다.

첫번째 부분: 요약 설명
두번째 부분: 상세 설명
이어지는 줄은 모두 태그로 시작
- @param, @return 등등 여러 태그 존재
- 링크를 걸때는 대괄호를 사용하면 된다

공식적인 코틀린 문서 생성 도구 이름: Dokka

규약

규약을 적절하게 정의해 정의된 규약에 따라 독립적으로 작업할 수 있도록 한다.

규약 정의하기

규약 정의하는 대표적인 방법은 다음과 같다.
1. 이름: 일반적인 개념과 관련된 메서드는 이름만으로 동작을 예측할 수 있다.
예를 들어 sum 이 있다.
2. 주석과 문서: 필요한 모든 규약을 적을 수 있는 강력한 방법이다.
3. 타입: 함수의 선언에 있는 리턴 타입과 아규먼트 타입은 큰 의미가 있다.

주석을 써야할까?

클린 코드 책으로 인해 주석없이도 읽을 수 있는 코드를 작성해야 하는 프로그래밍 방식으로 바뀌었다.

fun update() {
    updateUsers()
    updateBooks()
}

//함수로 의미 추출 
private fun updateUsers() {
    for (user in users) {
        user.update()
    }
}

private fun updateBooks() {
    for (book in books) {
        updateBook(book)
    }
}

하지만 주석을 함께 사용하면 더 많은 내용의 규약을 설명할 수 있다.

/**
 * Returns a new read-only list of given elements.  The returned list is serializable (JVM).
 * @sample samples.collections.Collections.Lists.readOnlyList
 */
public fun <T> listOf(vararg elements: T): List<T> =
    if (elements.size > 0) elements.asList() else emptyList()

읽기 전용이고 jvm에서 직렬화할 수 있는 리스트를 리턴한다
-> listOf 와 같이 코틀린 표준 라이브러리에 적힌 주석은 코드를 이해하는데 도움이 되기도 한다!!

타입 시스템과 예측

interface Car {
    /**
     * 자동차의 방향을 변경한다
     * 
     * @param angle 바퀴 각도를 지정함. 라디안 단위로 지정하며 0은 직진 의미
     * pi / 2는 오른쪽으로 최대한 돌렸을 경우, -pi / 2는 왼쪽으로 최대한 돌렸을 경우를 의미
     * 값은 (-pi / 2, pi / 2) 범위로 지정해야 함
     */
    fun setWheelPosition(angle: Float)

    /**
     * 자동차 속도가 0이 될 때가지 감속한다
     * 
     * @param pressure 브레이크 페달을 쓰는 비율. 0~1 사이의 숫자를 지정한다
     * 0은 브레이크를 안 쓰는 경우, 1은 브레이크를 최대한 사용하는 경우를 의미한다
     */
    fun setBreakPedal(pressure: Double)

    /**
     * 최대 속도까지 자동차를 가속한다
     * 
     * @param pressure 가스 페달(가속 페달)을 쓰는 비율. 0~1 사이의 숫자를 지정한다
     * 0은 가스 페달을 안 쓰는 경우, 1은 가스 페달을 최대한 쓰는 경우를 의미한다
     */
    fun setGasPedal(pressure: Double)
}