31장 - 문서로 규약을 정의하라

아이템 27에서 추상화를 통해 메시지를 출력하는 함수를 만들었습니다.

fun Context.showMessage(
	message: String,
	duration: MessageLength = MessageLength.Long
){
	val toastDuration = when(duration){
		SHORT -> LENGTH.LENGTH_SHORT
		LONG -> LENGTH.LENGTH_LONG
	}
	Toast.makeText(this, message, toastDuration).show()
}

enum class MessageLength {SHORT, LONG}

 

이때 showMessage라는 함수이름을 통해 토스트가 아니라 다른 타입으로도 출력할 수 있도록 이름을 붙였습니다.

하지만 다른 개발자는 이 코드를 읽고, 당연히 토스트를 출력할 것이라 생각할 수 있습니다.

 

따라서 함수가 무엇을 하는지 명확하게 설명하고 싶다면 주석을 붙여주는 것이 좋습니다.

/*
이 프로젝트에서 짧은 메시지를 사용자에게
출력할 때 사용하는 기본적인 방식입니다.
@param message 사용자에게 보여 줄 메시지
@param length 메시지의 길이가
어느 정도 되는지 나타내는 enum 값
*/

 

전문적인 용어 풀이

powerset에 대해서 아시나요?

powerset이란 멱집합이라는 명확한 수학적 개념입니다.

하지만 멱집합이 무엇인지 모르는 사람이 있을 수 있으므로 추가적인 설명이 필요할 수 있습니다.

/*
리시버의 집합과 모든 부분 집합을 리턴합니다.
자기 자신과 빈 집합을 포함합니다.
*/

 

만약 행위가 문서화되지 않고, 요소의 이름이 명확하지 않다면 이를 사용하는 사용자는 우리가 목표했던 추상화의 힘을 잃고 현재 구현에만 의존하게 됩니다.

 

주석을 써야 할까?

자바 커뮤니티 초기에는 '문학적 프로그래밍'이라는 개념으로 주석으로 모든 것을 설명하는 것이 굉장히 인기 있었습니다.

하지만 10년이 지난 현재는 주석 없이도 읽을 수 있는 코드를 작성해야 하는 프로그래밍 방식으로 바뀌었습니다.

 

극단적인 것은 언제나 좋지 않으며 주석과 클린코드를 활용한다면 더 많은 내용의 규약을 설명할 수 있게 됩니다.

 

KDoc 형식

주석으로 함수를 문서화할 때 사용되는 공식적인 형식을 KDoc이라고 부릅니다.

모든 KDoc /**로 시작해서 */로 끝납니다.

또한 일반적으로 모든 줄은 *으로 시작합니다.

 

- 첫 번째 부분은 요소에 대한 요약 설명

- 두 번째 부분은 상세 설명

- 이어지는 줄은 태그로 추가설명을 합니다.

 

KDoc 예시

/**
*이 프로젝트에서 짧은 메시지를 사용자에게
*출력할 때 사용하는 기본적인 방식입니다.
*@param message 사용자에게 보여 줄 메시지
*@param length 메시지의 길이가
*어느 정도 되는지 나타내는 enum 값
*/

 

다음과 같은 태그를 사용할 수 있습니다.

@param, @return, @constuctor, @throws, @author 등등 태그를 사용합니다.

 

 

이런 태그는 모든 코틀린 문서 생성 도구에서 사용됩니다.

공식적인 코틀린 문서 생성 도구의 이름은 Dokka입니다.

 

다양한 태그들을 활용하여 모든 것을 설명하는 것은 필요 없습니다.

짧으면서 명확하지 않은 부분을 자세하게 설명하는 문서가 좋은 문서입니다.

 

인터페이스와 규약

인터페이스의 규약에 대해 주석을 통해 자세한 설명으로 사용자는 해당 클래스에 대한 예측을 쉽게 할 수 있습니다.

특히 외부 API를 구현할 때는 규약을 잘 정의해야 합니다.

 

규약은 요소가 현재 어떻게 동작하고, 앞으로 어떻게 동작할지를 사용자에게 전달해 줍니다.

이를 기반으로 사용자는 요소를 확실하게 사용할 수 있고, 규약에 없는 부분은 변경할 수 있는 자유를 얻습니다.

 

규약은 단순한 합의지만, 양쪽 모두가 그 합의를 존중한다면 큰 문제는 없습니다.