javadoc을 이용해서 협업을 더 쉽게 해보자

사실 코틀린을 쓰는 우리는 Javadoc이 아니라, KDoc이긴 하지만... 어그로를 위해서 javadoc으로 제목을 정했습니다. 어차피 똑같잖아....

먼저 KDoc, Javadoc을 쓰는 이유는 무엇일까요? 누군가와 협업하기 위해, 수정사항에 대해서 히스토리를 남겨두기 위해 등등 결론적으로 보면 나의 코드를 남에게 조금더 쉽게 이해시켜주기 위해 작성하는 일종의 문서라고 생각하면 됩니다.

라이브러리를 받아 내부를 보다보면 클래스나 함수에 영어와 함께 설명이 쓰여져 있는 것을 볼 수 있습니다.

아래와 같이요!

다만 위의 사진은 java 클래스에서 쓰여진 javadoc이기 때문에 저희가 볼 KDoc이랑은 조금 다른점 알아두시면 좋습니다.

먼저 예시로 피타팻씨는 playMusic이라는 함수를 만들었습니다.

그런데 같이 프로젝트를 진행하던 현수씨는 곡명과 곡의 번호를 입력하는 함수라는 것은 알았습니다. 그러나 이 번호가 고유한 값인지, 음수의 값도 되는지, 어디부터 어디까지 가능한 값인지 전혀 알지 못해 피타팻씨에게 연락을 해봤지만, 피타팻씨는 안타깝게도 미모의 여자친구와 함께 롯데월드에 가 현수씨의 연락에 답장을 하지 못해 일정이 하루 딜레이가 됐답니다.

또한 수정이력이 많던 playMusic이라는 함수는 갓 입사한 3개월차 신입 현수씨는 왜 musicNumber라는 고유 값이 필요한지 이해조차 할 수 없었습니다.

이러한 상황을 방지하기 위해서 저희는 javadoc, 코틀린에서는 KDoc을 사용합니다.

KDoc은 javadoc과 비슷하게 /** */ 내부에 여러 정보를 써주면 됩니다. 또한 @과 함께 다양한 정보를 넣어주면 됩니다. 다음과 같이요!

이제 다른사람들이 함수를 보고 함수가 어떤 일을 하는지, 누가 언제 수정했고, 파라미터는 어떤게 필요한지, 리턴값은 어떤지 한번에 볼 수 있답니다.

또한 이런 javadoc, kdoc의 장점은 구현부가 아닌 호출부에서도 확인이 가능하단 점입니다.

playMusic() 메소드에 마우스를 올리면 이러한 정보들이 나오게 됩니다. 복잡한 함수나 긴 함수, 수정이 잦은 메소드나 클래스에는 꼭 적어주면 협업에 정말 도움이 될 것 같습니다.

또한 링크를 걸어 함수에서 다른함수를 보게해줄 수도 있는데요, 아래와 같이 @link와 함께 대괄호를 사용하면, 다른 함수로 이동할 수 있습니다.

@link의 stopMusic을 ctrl + 좌클릭하거나, ctrl + b를 하면 해당 함수로 이동합니다. 다만 @link는 꼭 걸지 않아도 되지만, 설명과 함께 링크라는 것을 알려주기 위해 관행적으로 사용해줍니다.

이러한 중요한 정보들 외에도 exception, sample, constructor, property 등 클래스나 함수의 익셉션이나 예시, 생성자나 프로퍼티 등 다양한 정보를 포함할 수 있습니다.

이번에 회사에서 히스토리 관리를 위해 처음으로 javadoc을 사용해보며, 복잡하거나 어려운 함수에 대해서 굳이 안예쁜 주석을 다는 것보다 깔끔하게 문서화 하면 더 히스토리 관리에 있어 좋다는 점을 배워 작성해보았습니다.

 

 

참고 : 문서 Kotlin 코드: KDoc 및 Dokka | 코틀린 (kotlinlang.org)

+ 내경험