[이펙티브 코틀린] Item31. 문서로 규약을 정의하라

'Item27. 변화로부터 코드를 보호하려면 추상화를 사용하라'에서 살펴보았던 메시지를 출력하는 함수처럼 추상화를 통해 만들어졌다면, 쉽게 이해하기 어려울 수 있습니다.

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

KDoc 주석은 일반적으로 함수와 클래스의 이름만으로 예측할 수 없는 세부 사항을 포함하고 있습니다.

 

 

규약

 

어떤 행위를 설명하면 사용자는 이를 약속으로 취급하며, 이를 기반으로 스스로 자유롭게 생각하던 예측을 조정합니다.

규약을 정의해두면, 클래스를 만드는 사람과 사용하는 사람 모두 미리 정의된 규약에 따라 독립적으로 작업할 수 있습니다.

 

 

규약 정의하기

 

규약을 정의하는 방법은 다양합니다.

 

• 이름: 일반적인으로 이름만으로 동작을 예측할 수 있다.
• 주석과 문서: 모든 규약을 적을 수 있는 방법이다.
• 타입: 타입은 객체에 대한 많은 것을 알려준다. 리턴 타입과 아규먼트 타입은 큰 의미가 있으며, 자주 사용되는 타입의 경우에는 타입만 봐도 어떻게 사용하는지 알 수 있지만, 일부 타입은 문서에 추가로 설명해야 한다.

 

KDoc 형식

 

주석으로 함수를 문서화할 때 사용되는 공식적인 형식을 KDoc이라고 부르며, /**로 시작해서 */로 끝납니다.

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

KDoc 주석의 구조는 다음과 같습니다.

 

• 첫 번째 부분은 요소에 대한 요약 설명
• 두 번째 부분은 상세 설명
• 이어지는 줄은 모두 태그로 시작하며, 추가적인 설명을 위해 사용된다.

 

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

 

• @param <name>: 함수 파라미터 또는 클래스, 프로퍼티, 함수 타입 파라미터
• @return: 함수의 리턴 타입 값
• @constructor: 클래스의 기본 생성자
• @receiver: 확장 함수의 리시버
• @property <name>: 이름을 갖고 있는 클래스의 프로퍼티, 기본 생성자에 정의된 프로퍼티에 사용
• @throws <class>, @exception <class>: 메서드 내부에서 발생할 수 있는 예외
• @sample <identifier>: 정규화된 형식 이름을 사용한 함수의 사용 예
• @see <identifier>: 특정한 클래스 또는 메서드에 대한 링크
• @author: 요소의 작성자
• @since: 요소에 대한 버전
• @supress: 이를 지정하면, 만들어지는 문서에서 해당 요소가 제외된다. 공식 API에 포함할 필요가 없는 요소에 지정\

 

---

정리

 

• 요소, 특히 외부 API를 구현할 때는 규약을 잘 정의하자
• 규약은 이름, 문서, 주석, 타입을 통해 구현할 수 있다.
• 규약은 사용자가 객체를 사용하는 방법을 쉽게 이해하는 등 요소를 쉽게 예측할 수 있게 해준다.