[Effective Kotlin] Item 31 : Define contract with documentation

이 글은 Effective Java 를 완독하고, Kotlin 을 상용으로 사용하는 개발자 입장에서
Effective Kotlin 글 중 새로운 내용, remind 할 필요 있는 부분, 핵심 내용 등만 추려 정리한 내용입니다.

 

#
이름이 말하는 바가 불투명하거나 문서화가 제대로 되어 있지 않다면, 개발자는 원래 의도가 아닌 현재 구현을 바탕으로 판단한다.

 

 

Contract

#
규약이 잘 정의되어 있다면, 제작자 측면에서 이 녀석이 어떻게 사용될지 걱정할 필요가 없어지고, 사용자 입장에서는 어떻게 구현되었는지를 신경쓸 필요가 없어진다.
만약 규약이 잘 정의되어 있지 않다면, 유저는 무엇을 해도 되는지 하면 안 되는지 잘 몰라서 구현을 보고 이를 따르게 된다. 제작자는 유저가 무엇을 원하는지 모르기 때문에 추후 수정으로 유저의 구현을 망칠 수도 있다.

 

 

Defining a contract

#
이름, 주석, 문서, 타입

 

 

Do we need comments?

#
개발 초반에는 모든 것에 주석을 다는 것에서, 최근에는 가독성 있는 코드로 주석을 대체하는 것으로 경향이 바뀌었다.
뭐든 극단적인 것은 좋지 않다.
가독성 있는 코드를 작성하는데 집중하고, 여기서 추가로 보강할 것이 있다면 주석을 작성하자.

 

#
주석은 그 자체로 문서화될 수도 있으므로, 잘 작성하는 것이 좋다.

 

#
주석은 보통 extract 로 이어진다. (주석이 삭제되고 함수가 된다.)

 

 

KDoc format

#
첫 파트는 summary, 두번째 파트는 디테일.
@param, @return, @throws, @see 등의 param 이 온다.

 

#
Kotlin 에서는 Dokka 라는 녀석이 공식적인 문서 생성 툴이다.

 

 

Type system and expectations

#
inteface 또는 class 가 어떠한 것을 약속한다면, 그 subclass 들도 모두 그 규약을 지켜야 한다.
이를 Liskov substitution principle 이라 부른다.
이를 다시 말하면 "만약 S 가 T 의 subtype 이라면, T type object 는 S type object 로 교체 할 수 있다." 이다.

 

#
interface 의 param 값과 return 값의 범위나 제약 등이 잘 명시되어야 한다.

 

 

Leaking implementation

#
reflection 등으로 구현이 누수될 수 있다.

 

 

Summary

 

끝