- 이 함수가 무엇을 하는지 명확하게 설명하고 싶다면, KDoc 주석을 붙여 주는 것이 좋습니다.
- 일반적인 문제
- 행위가 문서화되지 않고, 요소의 이름이 명확하지 않다면 이를 사용하는 사용자는 우리가 만들려고 했던 추상화 목표가 아닌, 현재 구현에만 의존하게 된다는 것입니다.
- => 예상되는 행위를 문서로 설명 함으로써 해결합니다.
- 어떤 행위를 설명하면 시용자는 이를 일종의 약속으로 취급하며, 이를 기반으로 스스로 자유롭게 생각하던 예측을 조정합니다.
- 예측되는 행위를
요소의 규약(contract of an element)이라고 부릅니다. - 규약이 적절하게 정의되어 있다면,
- => 클래스를 만든 사람은 클래스가 어떻게 사용될지 걱정하지 않아도 됩니다.
- 서로가 규약을 존중한다면,
- => 독립적으로 작업해도 모든 것이 정상적으로 기능할 것입니다. 이는 모두에게 편안함과 지유를 줍니다.
- 이름
- 주석과 문서
- 타입
- 커뮤니티 의견의 변화
- 자바 커뮤니티 초기 : ‘문학적 프로그래밍(literate programming)' 이라는 개념이 인기
- 10년이 지난 후 : 주석 없이도 읽을 수 있는 코드를 작성해야 하는 프로그래밍 방식으로
- 문서는 프로젝트에서 가장 진실된 내용이 적힌 곳으로 취급됩니다.
- 함수 이름과 파라미터만으로 정확하게 표현되는 요소에는 따로 주석을 넣지 않는 것이 좋습니다.
- 예시) 코틀린 표준 라이브러리의 모든 public 함수
- 이 함수들은 규약을 잘 정리해 주므로, 사 용자에게 지유를 줍니다.
- 주석으로 함수를 문서화할 때 사용되는 공식적인 형식을 KDoc 이라고 부릅니다.
- KDoc 주석은 /**로 시작해서 */ 로 끝남
- 이 사이의 모든 줄 은 일반적으로 *로 시작
- 설명은 KDoc 마크다운이라는 형식으로 작성
- KDoc 주석의 구조
- 첫 번째 부분은 요소에 대한 요약 설명 (summaty description)입니다.
- 두 번째 부분은 상세 설명입니다.
- 이어지는 줄은 모두 태그로 시작합니다. 태그는 추가적인 설명을 위해 사용됩니다.
- 관련된 요소 둥에 링크를 걸 때는 대괄호를 사용합니다. 만약 링크 대상에 대한 추가 설명을 입력하고 싶을 때는 대괄호를 두 번 연속해서 사용합니다.
- 공식적인 코틀린 문서 생성 도구의 이름은 Dokka 입니다.
- 짧으면서 명확하지 않은 부분을 자세하게 설명하는 문서가 좋은 문서 입니다.
타입 계충(type hierarchy)은 객체와 관련된 중요한 정보입니다.- 인터페이스는 우리가 구현해야 한다고 약속한 메서드 목록 이상의 의미를 갖습니다.
- 리스코프 치환 원칙 (Liskov substitution principle)
- 클래스가 어떤 동작을 할 것이라 예측되면, 그 서브클래스도 이를 보장해야 합니다.
- ‘S가 T의 서브타입이라면, 별도의 변경 이 없어도 T 타입 객체를 S 타입 객체로 대체할수 있어야 한다'
- 사용자가 클래스의 동작을 확실하게 예측할 수 있게 하려면, 공개 함수에 대한 규약을 잘 지정해야 합니다.
- 표준 라이브러리와 인기 있는 라이브러리에 있는 대부분의 클래스는 그 서브클래스 (와 요소)에 대한 자세한 설명과 규약을 갖고 있습니다.
- 언어는 어떤 식으로 작동해도 괜찮지만, 좋은 방식들을 기억하고 이를 적용해서 사용하는 것이 좋습니다.
- 구현의 세부 사항온 항상 달라질 수 있지만, 최대한 많이 보호하는 것이 좋습니다.
- 일반적으로 캡슐화를 통해서 이를 보호합니다.
- 캡슐화는 ‘허용하는 범위’ 를 지정하는 데 도움을 주는 도구입니다.
- 캡슐화가 많이 적용될수록, 시용자가 구현에 신경을 많이 쓸 필요가 없어지므로, 더 많은 자유를 갖게 됩니다.
외부 API(external API)를 구현할 때는 규약을 잘 정의해야 합니다. 규약은 이름,문서,주석,타입을 통해 구현할 수 있습니다. 규약은 사용자가 객체를 사용하는 방법을 쉽게 이해하는 등 요소를 쉽게 예측할 수 있게 해 줍니다.
규약은 요소가 현재 어떻게 동작하고, 앞으로 어떻게 동작할지를 사용자에게 전달해 줍니다. 규약은 단순한 합의지만, 양쪽 모두가 그 합의를 존중한다면 큰 문제가 없을 것입니다.