TIL

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

• 함수가 무엇을 하는지 명확하게 설명하고 싶다면, KDoc 주석을 붙여주는 것이 좋다.

/**
* 프로젝트에서 짧은 메시지를 사용자에게
* 출력할 때 사용하는 기본적인 방식
* @param message 사용자에게 보여줄 메시지
* @param length 메시지 길이를 나타내는 enum 값
*/
fun Context.showMessage(/*...*/) { /*...*/ }

• 대부분의 함수와 클래스는 이름만으로 예측할 수 없는 세부 사항들을 갖고 있다.
• 행위가 문서화되지 않고 요소 이름이 명확하지 않다면 추상화 목표와는 다르게 현재 구현에만 의존하게 될 수도 있다.
  • ex) 메서드 이름은 showMessage지만 내부적으로 토스트를 출력하고 있다면 앞으로도 계속 토스트만 출력하게될 수도 있다.

규약

• 규약이 적절히 정의되어 있다면 클래스가 어떻게 사용될지 걱정을 덜 수 있다.
• 클래스를 사용하는 사람은 구현을 자세히 알지 못해도 규약을 믿고 구현을 믿을 수 있다.
• 규약을 설정하지 않는다면
  • 클래스를 사용하는 사람이 구현의 세부 정보에 의존하게 된다.
  • 클래스를 만든 사람은 사용자가 무엇을 할지 알 수 없으므로 구현을 망칠 위험이 있다.

규약 정의하기

• 이름 - 일반적인 개념이라면 메서드 이름만으로 충분히 동작을 예측할 수 있다. (ex. sum())
• 주석과 문서 - 필요한 규약을 적을 수 있는 강력한 방법
• 타입 - 함수 선언의 리턴 타입과 아규먼트 타입은 많은 것을 알려준다. 타입만 보아도 규약을 알수도 있지만 추가로 설명이 필요한 경우도 있을 것이다.

주석을 써야 할까?

• 자바 커뮤니티 초기에는 ‘문학적 프로그래밍’이라 해서 주석으로 모든 것을 설명하려 했다.
• 하지만 로버트 마틴의 ‘클린 코드’ 이후 주석 없이도 읽을 수 있는 방식이 유행하게 되었다.
• 이름 등으로 무엇을 하는지 명확히 알 수 있다면 주석은 불필요 하다.
  • 아래 예제 코드는 주석이 필요 없고 오히려 노이즈이다.

fun List<Int>.product() = fold(1) { acc, i -> acc * i }

• 또한 주석을 다는 것보다 함수로서 추출하는 것이 훨씬 좋다.

// 주석으로 표현하기
fun update() {
	// 사용자를 업데이트 합니다.
	for (user in users) {
		user.update()
	}
	
	// 책을 업데이트 합니다.
	for (book in books) {
		updateBook(book)
	}
}

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

private fun updateUsers() { /*...*/ }

private fun updateUsers() { /*...*/ }

• 하지만 주석은 굉장히 유용하고 중요한데 코틀린 표준 라이브러리의 모든 public 함수는 주석으로 규약을 나타내는 경우가 매우 많다.

KDoc 형식

• KDoc의 모든 주석은 /**로 시작해서 */로 끝난다.
• KDoc 주석 구조는 다음고 같다.
  • 첫 부분은 요소에 대한 요약 설명
  • 두 번째 부분은 상세 설명
  • 이어지는 줄은 모드 태그로 시작하여 추가 설명을 위해 사용된다.
• 사용할 수 있는 태그는 다음과 같다.
  • @param <name>: 함수 파라미터 또는 클래스, 프로퍼티 등을 문서화
  • @return: 함수의 리턴 값을 문서화
  • @constructor: 클래스의 기본 생성자를 문서화
  • @receiver: 확장 함수의 리시버를 문서화
  • @property <name>: 명확한 이름을 갖는 프로퍼티를 문서화 (기본 생성자에 정의된)
  • @throw <class>, @exception <class>: 메서드 내부에서 발생할 수 있는 예외를 문서화
  • @sample <identifier>: 정규화된 형식 이름을 사용해서 함수의 사용 예를 문서화
  • @see <identifier>: 특정 클래스 또는 메서드에 대한 링크를 추가
  • @author: 요소의 작성자를 지정
  • @since: 요소에 대한 버전을 지정
  • @supress: 이를 지정하면 만들어지는 문서에 해당 요소가 제외되는데 외부에서 사용 가능하지만 공식 API에 필요 없는 요소에 지정
• 모든 것을 설명할 필요는 없다.
• 짧으면서 명확하지 않은 부분을 자세히 설명하는 문서가 좋은 문서다.

타입 시스템과 예측

• 클래스가 어떤 동작을 할 것이라 예측되면 서브 클래스도 이를 보장해야 하는데 이를 리스코프 치환 원칙이라 한다.
• 사용자가 클래스 동작을 확실히 예측할 수 있게 하려면 공개 함수에 대한 규약을 잘 지정해야 한다.

interface Car {
	fun setWheelPosition(angle: Float)
	fun setBreakPedal(presuure: Double)
	fun setGasPedal(pressure: Double)
}

• 위 인터페이스의 파라미터나 단위 등에 의문이 든다면 이러한 것들은 모두 문서를 통해 전달할 수 있다.

interface Car {
	/**
	* Change car direction
	*
	* @param angle 바퀴 측 각도를 지정합니다.
	* ...
	*/
	fun setWheelPosition(angle: Float)
	// ...
}