소통의 중요성... feat. JSdoc

서두

이번에 입사하면서 회사 코드를 확인했는데 여러모로 쉽지 않았다. 

왜 nest가 인기가 많은지 새삼 체감하는게, express가 워낙 자유도가 높다고는 하지만,

변수명 빼고는 모든 부분이 들여다봐야 이해가 가능했다. 

 

이미 전 포스트에서 sql인젝션에 대비하지 않고 쿼리문에 직접 변수를 넣는 것부터 어느정도 나의 포지션에 대해 직감하고 있는 중이다...ㅎㅎ 

 

당장 api를 수정해서 적용해야 하는 일이 있었는데, 소통하면서 개발하는 단계면 상관없는데 테스트하자마자 바로 서버에 적용을 해야하는 상황이라서 에러처리를 확실히 해야하는데 이미 구현되어있던 api들을 보았을 때 에러처리가 명확하지 않은 부분들이 있기도 했고, 설명하긴 너무 길어지고.. db관련 에러를 throw하지 않고 컨트롤러로 옮기는 등.. 방식 자체가 달랐다. 

 

할말은 많지만 나역시 초보 신입 개발자가 답답해봤자 내 코드도 별반 다르지 않을 것이라는 것을 알기에.. 

코드를 뜯어보면서 느끼는 것은, 기능적인 부분에 대해서는 어차피 로직을 읽어봐야 제대로 아는거니까 넘어가겠지만 적어도 변수를 읽었을 때 api명세서와 바로 대조될 수 있도록 하면 좋겠다는 것이였다. 

 

발단

예를 들면, 자가진단api (diagnosis)는 이렇게 있었다. 

- 회원 진단 저장 post

- 자가진단 리스트 get

- 자가진단 상세조회 get

- 최근 진단내역 리스트 get

- 최근 진단내역 카운트 get

 

그래서 나는 딱 이름을 봤을 때 아, 회원들이 자가진단을 하고 자가진단 목록과 하나를 선택하면 상세조회를 할 수 있다고 생각했다. 

url도 실제로 diagnosis, diagnosis/${diagnosis_id} 로 되어 있기도 해서 당연히 그렇게 생각했다. 

 

그런데 자가진단 리스트, 자가진단 상세조회는 JWT 미사용에 체크가 되어있었다. DB와 대조해보고 나서 이해했다. 자가진단 리스트는 자가진단을 하게 되면 나오는 설명들, 상세조회는 자가진단 문항 및 4지선다 체크항목이였다. 

 

사실 나는 읽어보고 이해를 하는 입장이니까 이해를 못하고 답답해했던 부분이지만, 작성한 본인은 당연스럽게 썼을 것이다. 결국 내가 바보인 탓인거지.. 그래서 이런 일을 미연에 방지하고자 아이덴테이션을 모호하지 않게 해야하겠다고 느꼈다. 

 

 

과정 1. 네이밍 및 crud 별 명확한 api 구분

그러기 위해서는 crud가 유기적으로 연결이 되어야 한다고 생각했다. 

당장 내가 바로 이해하지 못한 이유가, 저장을 했으니까 조회, 수정, 삭제가 있겠다는 1차원적인 생각을 당연하게 했는데,

post 다음에 나온 get은 post를 하기 위한 get이였다. crud로 묶는다면 자가진단 리스트, 상세조회는 자가진단 문항 이런식으로 이름을 확실히 해서 user과는 분리를 하는 것이 좋을 것 같다. 

 

과정 2. JSdoc 이용한 주석 

많지는 않지만 프로젝트를 몇 차례 경험해보니 구조상 crud가 유기적으로 이루어지지 못하는 부분이 간혹 있을 수 있는 것 같다. 한 두개의 api때문에 디렉토리를 새로 만들기 애매할 수도 있고, 사실 이 경우도 비슷하게 생각할 수 있을 것 같은데, 그럴 때 이용하면 좋을 것 같다. 

 

이전 프로젝트를 리팩토링하면서 진행한 부분인데 자세한 내용은 참고해도 좋겠다. 

https://prpn97.tistory.com/105

[엘리스트랙 SW 4기 | 2차 프로젝트 복기] 소통왕 프로젝트 / 별도의 docs를 작성하여 jsdoc 주석 적용

 

 

간단하게는 아래와 같이 변수 위에 작성할 수 있다. 

/**
 * 자가진단 리스트 (자가진단 설명)
 */
 export const getDiagnosisList = async (req, res, next) => {

작성하고 호버하게 되면 다른 파일에서도 해당 변수에 마우스를 호버하면 설명이 보인다. 

위 프로젝트는 JS라서 매개변수에 타입이 any로 보이지만, TS에서도 동일하게 사용할 수 있고, 지정한 인스턴스나 타입에 대해서도 확인할 수 있다. 또한 @params 등 작성할 수 있는 여러 기능들이 있다. 

 

 

코멘트

당장 해당 api는 내가 구현하고 내가 이해하고 그만이라고 생각하면 할 말은 없다. 그러나 협업을 한다면, 다른 사람이 나의 코드를 읽어야 하는 상황이 1%라도 있다면 방법이 꼭 이 방법은 아니여도 상관없지만 그 어떤 프로젝트라도 대부분 통일되어 있는 내용이 아니라면 쉽게 이해할 수 있는 무언가를 전달해주면 좋을 것 같다. 

 

*덕분에 회사 다닌지 하루만에 nest를 공부해야겠다고 느꼈고, 기본 구조에 대해 익히고 있는데 위 고민들이 점점 해결되어가는 것 같다..?