[Item56] 주석은 죄가 아니다

Item56에서는 공개된 API 요소에는 항상 문서화 주석을 작성하라 말한다

사실 언어나 프레임워크, 공개 라이브러리 작성자가 아니라면 지키지 않아도 될 조언이긴 하다

다만 구멍가게를 벗어나 네이버와 같이 하나의 회사지만 여러 계열사로 나뉘고

그 안에서 공통적으로 사용할 모듈을 개발한다면 의무는 아니어도 javadoc 형태로 작성해두면 사용하는 이들에게 좋다

나는 수습 과제로 만든 작은 사이드 프로젝트에 주석을 적어놓기도 했다

 

 

클린 코드에 미친 사람이라면 주석 자체가 쓰레기 같겠지만

분명한 건 코드를 짜는 순간부터 레거시가 되고 자신이 평생 유지보수할 수는 없다는 것이다

그렇다면 다음 사람이 이를 맡아서 유지보수를 해야 하는데 도메인 지식이라고도 하고, 배경지식이라고도 하는

특정 비지니스 로직을 모르고 있는 이에게는 아무리 잘 짜인 코드라도 쉽게 이해할 수는 없기 마련이다

그럴 때 문서화가 큰 도움이 될 수 있다

문서화를 하더라도 신경써야 하는 점은 어떻게 How, 수행하는지가 아닌 어떤 What 작업을 수행하는지 표현해야 한다

즉, 어떤 작업을 하는지를 주석으로 표현하고 어떻게 작업하는 지는 코드를 보면 알 수 있게 만들어야 한다

 

위 사진을 봤을 때 완벽한 주석이라 할 수는 없다

그래도 왜 타원곡선 알고리즘 중 Ed25519를 선택했는지 보안성에는 어떤 요소들이 영향을 미치는지를 파악할 수 있다

애초에 암호화 알고리즘이라는 특수성 때문에 주석으로 모든 설명은 불가하다

그 대신 학습 테스트라고 하는 API 사용법을 익히는 테스트를 잘 짜 놨기 때문에 저 정도만 설명하고

자세한 내용은 학습 테스트와 추가적인 서치로 해결하라고 남겨뒀다

 

javadoc의 진가는 초보자 시절에는 알 수 없다

구글에서 한글 검색을 벗어나 공식 레퍼런스를 찾아보거나 공신력 있는 사이트에서 정보를 얻을 때부터 시작된다

어느 사이트보다 정확한 것이 javadoc이기 때문이다

직접 개발한 사람이 API 설명을 위해 남겨둔 것이고 그 사람이 설계 때부터 가졌던 가정, 조건들이 나열되어 있다

아래 사진은 자바는 아니지만 도움이 될 것 같아 가져왔다

rust의 String::from 사용에 관한 주석인데 &str 타입이 String 타입으로 변환된다는 것을 설명하고

거기다 결과 값이 heap에 올라간다는 친절한 설명까지 덧붙여져 있다

 

 

사용하는 입장에서 이 놈이 heap에 올라가던 method에 올라가던 stack에 올라가던 알 바 아니라고 생각할 수도 있는데

저 놈이 heap에 올라가게 돼서 발생하는 이슈가 무엇인지도 알아야 하고 언제 없어지는지도 알아야 한다

 

최근 코드 리뷰를 받을 때마다 코드 한 줄을 작성하더라도 분명한 이유가 있어야 한다는 것을 느낀다

혼자 개발할 때는 작동하는 프로그램을 많이 짜는 게 개발을 잘하는 거라 생각했었다

지금은 예를 들어 Spring MVC가 어떤 마법을 부려 @RequestParam, @ModelAttribute를 매핑해주는지,

JSON이 아닌 XML 방식의 통신을 위해서는 어떤 제약 사항이 따르고 이를 지켜야 하는지

이런 복잡한 사항들의 원리를 파악하는 것이 정말 개발을 잘하는 거라 생각한다

단순한 API를 쓰더라도 내부적으로 어떻게 사용되는지 어떤 side effect가 날 수 있는지 아는 게 중요하다

 

내가 속한 팀의 코드 리뷰는 <함께 자라기>라는 책에서 읽은 코드 리뷰 문화와는 사뭇 차이가 있다

처음에는 말랑말랑한 리뷰가 아니어서 놀랐는데 몇 번 겪고 적응하다 보니까 나는 빡시게 들어오는 게 좋은 것 같다

원래 쪽팔린 순간이 기억에 오래 남고 그렇게 씨게 들어오면 공부를 안 할 수가 없다

코드를 작성하면서도 내 코드를 비판적으로 바라볼 수도 있고 암튼 좋은 것 같다

결론으로 제일 상세한 문서인 javadoc을 참고하고 사내에서 널리 쓰일 모듈의 개발자라면

단순 사용법만 나열하지 말고 사용자의 깊은 이해를 위해 javadoc 뺨치는 문서도 남겨보자