아이템 31 - 문서로 규악을 정의하라

• KDoc 스타일로 주석을 남긴다.
  • 이해도 향상
    • 문서화된 코드는 다른 개발자가 더 쉽게 이해할 수 있다.
  • 유지보수성 증가
    • 명확한 문서화는 코드의 유지 보수성을 높인다.
    • 코드의 사용 방법과 제약 사항을 이해하고, 이를 토대로 수정하거나 개선할 수 있다.
  • 사용자 신뢰 증가
    • 문서화된 코드는 사용자에게 신뢰감을 준다.

/**
 * 요소가 추가된 횟수를 기록하는 세트.
 *
 * @param T 세트에 포함된 요소의 타입
 * @property elementsAdded 세트에 추가된 요소의 수
 */
class CounterSetKDoc<T>(
    private val innerSet: MutableSet<T> = mutableSetOf()
) : MutableSet<T> by innerSet {
    /**
     * 세트에 추가된 요소의 수.
     * 중복된 요소나 이미 존재하는 요소를 추가하려고 시도한 경우도 포함됩니다.
     */
    var elementsAdded: Int = 0
        private set

    /**
     * 지정된 요소를 세트에 추가합니다.
     *
     * @param element 추가할 요소
     * @return 요소가 세트에 이미 존재하지 않아 추가된 경우 `true`, 그렇지 않으면 `false`
     */
    override fun add(element: T): Boolean {
        elementsAdded++
        return innerSet.add(element)
    }

    /**
     * 지정된 컬렉션의 모든 요소를 세트에 추가합니다.
     *
     * @param elements 추가할 요소들이 포함된 컬렉션
     * @return 세트가 변경된 경우 `true`, 그렇지 않으면 `false`
     */
    override fun addAll(elements: Collection<T>): Boolean {
        elementsAdded += elements.size
        return innerSet.addAll(elements)
    }
}

위 코드는 아래와 같이 보이게 할 수 있다.

 

- 적당히 KDoc 스타일로 너무 과하지않게, 필요에 따라 잘남기자.
- 함수 이름을 잘 적는게 중요할듯 하다.명확하게 보이게끔.