202109 til - 3분기 회고

Sorbet·2021년 9월 25일

클린코드를 읽고나서 쓰는 21년 3/4 분기 회고글

21년 6월~9월까지의 회고

해당 기간동안 개발을 하면서 느낀점을 간단하게 회고 해 보겠습니다. 토픽 몇개를 중심으로 하고싶은말을 적어 보려고 합니다

첫번째 - 작명센스를 키우자

고객관련 도메인이 있었는데, ~Client~ 라고 이름을 붙였었는데, 이게 좀 업무를 진행하다 보니까 우리회사는 FrontEnd 라는 용어보다는 클라단~ 클라가~ 이런 용어를 자주 써서 그런지, 생각보다 좀 의사소통하는데 주의가 필요했다. 그래서 ~Client~ 라는 단어를 다 걷어내고 Customer 라는 워딩으로 용어를 변경했는데, 이게 변경을 코드에만 해야되는게 아니라, 나름 정리해놓은 구글독스 문서에도, MySQL로 작성해놓은 ER-D 파일에도 수정이 필요했고 기타 등등.. 생각보다 용어하나 변경하는데 꽤 많은 공수가 들어갔습니다.
내가 담당한 부분이 POC 느낌의 파일럿 프로젝트라서 금방 고치고, 용어 변경 사실을 두세명 남짓한 회사동료분들에게 말씀드리면 되서 "호미로 아슬아슬하게 막은정도" 라고 생각이 들었습니다. 처음에 용어에 대해 고민을 조금만 더 했어도 아낄수 있었던 반나절 남짓의 시간과 그동안의 혼동을 반성합니다.

두번째 - 숨은 의미 없이 읽기 좋은 코드를 만들자

가격의 총합을 구매해야 하는 상황에서, 예를들어 아이템 A,B,C가 각각의 수량과 가격을 가지고 있을때, 이 세가지 아이템의 구매총액을 구해서 리턴해줘야 하는 상황이 있었습니다. 단순히 stream을 사용해서 하면 풀리겠지만, 여기서 한가지 기능이 추가됩니다. 도메인의 특수성으로 인해 가격과 수량이 정확해도 특정 Boolean flag 가 Bool.False일 때는 해당 품목의 가격을 무조건 0으로 만들어줘야 하는 상황이였습니다.
처음 만든 코드는 삼항 연산자를 이용해서

 .stream~
 .getIsFlag() ? value.multiply(0) : value.multiply(1)
 .stream~

이후 이해가 안된다는 민원을 받고 코드를 읽어보니 숨은의미, 더러운 코드였습니다. 어차피 결과에 영향을 미치지 않게 될 연산을 열심히 처리하고 나서 곱하기 0으로 만들어 버리는, 불필요한 연산도 추가하고 가독성도 좋지 못한 코드라는걸 인지하고 나서

.filter(obj -> !obj.getIsFlag())
.stream~
.stream~

위의 방식으로 조금 더 다듬었습니다. stream 상류에 filter로 결과에 영향을 미치지 않는 부분은 연산조차 하지 않도록 수정했습니다. 훨씬 보기도 좋아지기도 했습니다.

세번째 - 좋은 API 문서를 제공하려면 어떻게 해야할까 더 고민하자

백엔드 개발자가 작성한 API를 사용해서 프론트엔드 개발자가 사용하기 위해서는 API 사용법을 담은 문서가 꼭 필요합니다. API사용법을 담은 문서를 처음부터 끝까지 작성하기는 시간도 오래걸리고 어려우니, Java진영에서는 여러가지 문서화 가이드 툴을 제공합니다. 기존에 swagger를 사용했는데, 좀더 입맛대로 튜닝하기 위해서 && 여러가지 이유로 REST Docs를 개인적으로도 회사에서도 처음으로 도입해서 사용했습니다. 처음 도입하며 주로 참고한 링크는 우형 기술블로그에 이호진님께서 기고 해 주신 2018년글을 많이 참고했습니다.
2021년의 초보개발자인 제가 REST Docs를 진행하면서, 여러가지 문제점들이 있었는데요, 예를들어서 문서상에 표시되는 Serverside Endpoint의 url이 항상 "localhost:8080/api/~" 으로 시작되었는데, 사실 접속해야하는 주소는 "mysite.dev/api/~" 로 접속해야 되서, 포트번호와 도메인네임을 변경하는 문제, 한글이 깨지는 문제(모든 한글이 ??? 로 표시되는), POST REQUEST에서 한글이 하나라도 포함되어 있다면, 500에러가 발생하는 문제 등등(다행히 위 두문제는 Filter를 걸어주고 UTF-8 인코딩을 명시해주니 쉽게 해결됬습니다) 다양한 문제가 있었지만, 착하고 실력좋은 개발자 선생님들께서 친절하게 잘 작성 해 주신 문서들을 보면서 해결할 수 있었습니다.
하지만 해결되지 않은 문제가 하나 더 남아있습니다. 가장 중요하면서도 REST Docs를 도입하게 된 장점인 동시에 단점인데요, 바로 "문서의 모든 포멧과 형식을 직접 작성해야 한다" 라는 부분입니다. REST Docs를 사용하신 분들(최근에 코쿼에서 같이 공부하던 분도 도입하시던데 ㅎㅎ)도 공통적으로 느끼는 어려운점은, REST Docs가 그 자체로 문서를 바로 Generation해 주지는 않습니다. 이 모듈은 그저 snippet 조각들만을 제공 해 줄 뿐이고, 목차라던지, 동일한 정보를 표시하기 위해 설명박스로 해야할지, 표로 정리해야 할지는 모두 사용자(개발자)의 몫 이게 됩니다. 또한 하나의 get method API를 활용하기 위해서는 다른 문서화지원 패키지들이 정해진 형식이 있는데, EST Docs는 그런거 없습니다. 그냥 처음부터 다 직접 만들어야 합니다... ㅠㅠ
몇번의 시행착오 끝에 POC 프로젝트를 성공적으로 수행했고, 모든 엔티티 & 도메인들의 API를 문서화하는데는 성공했습니다. 하지만 많은 시간을 투입해야 했고, API 문서를 만들때 사용해야 하는 ASCIDOC 이라는 새로운 문법을 배우는 러닝커브라는 장벽, 작성하는 사람도 보는 사람도 생소한 API가이드 문서를 많은 시간을 투입해서 만든것 치고는 제 글쓰기 실력이 많이많이 아쉬워서 안타까웠습니다.
비유하자면, 성장 잠재력은 높은데, 파일럿(개발자)의 숙련도와 높은 실력이 요구되는 LoL의 챔피언 잭스가 떠오르는 그런 모듈이 RESTDOCS 였습니다