주석과 문서 활용하기
Chapter 7. 코드베이스 적응
"이거 코드 볼때 도움이 될만한게 없나?"
코드를 열었다. 함수명 processData
'데이터를 처리한다... 그건 알겠는데, 어떤 데이터를? 어떻게 처리하는데?'
파라미터가 3개다.input, options, callback
'input은 뭘 넣어야 하지? options는 어떤 옵션? callback은 언제 호출되는 거지?'
함수 안을 들여다본다. 200줄. 복잡하다.
'아... 이거 다 읽어야 하나?'
그리고 API를 호출해야 한다. 엔드포인트
/api/v2/users/update
'어떤 데이터를 보내야 하지? 응답은 어떻게 오지? 에러는 어떻게 처리하지?' 벌써 부터 막막하다.
막막하지만 방법이 있다. 코드만 보고 이해 하지 않아도 된다. 참고할 문서도 있고 주석이 있다. API 명세서라는 친절한 메뉴얼도 있다. 이번에는 나를 돕는 친절한 문서들을 어떻게 찾고 활용하는지 정리했다.
인라인 문서란?
인라인 문서는 코드 바로 위에 붙어있는 주석을 말한다. 함수가 뭘 하는지, 파라미터가 뭔지, 리턴값이 뭔지 설명한다. 이게 왜 중요할까?
함수 하나를 이해하려고 수 백 줄 코드를 다 읽는 건 비효율적이다. 인라인 문서가 있으면 5초 만에 이해할 수 있다. 입구와 출구만 우선 알 수 있게 해서 내부 구조를 보지 않아도 대략적인 기능을 알 수 있기 때문이다.
JSDoc, Javadoc, Docstring
인라인 문서는 언어마다 형식은 다르지만 목적은 같다. JavaScript는 JSDoc, Java는 Javadoc, Python은 Docstring이라고 다양하게 부른다. 방식은 비슷하다. 함수 위에 특별한 형식의 주석을 다는 방식이다.
예를 들면
/**
* 사용자 정보를 업데이트합니다
* @param {number} userId - 사용자 ID
* @param {Object} userData - 업데이트할 데이터
* @returns {Promise<User>} 업데이트된 사용자
*/
이 주석 하나로 알 수 있는 것:
첫 번째 파라미터는 숫자 (사용자 ID)
두 번째 파라미터는 객체 (업데이트할 데이터)
리턴값은 Promise이고 User 객체를 담고 있음
함수 안을 들여다보지 않아도 쓸 수 있게 만들어 준다.
API 문서는 개발자의 친구
백엔드 API든 외부 API든 어떤 데이터를 보내야 하는지, 응답은 어떻게 오는지, 에러는 어떻게 처리하는지.
이걸 다 코드를 보고 분석하는건 꽤나 어렵고 시간이 많이 든다. 그럴땐 API 문서를 보면 된다.
Swagger (OpenAPI)
가장 흔한 API 문서 형식이다. 보통 회사 내부 API는 Swagger로 문서화되어 있다.
보통의 경우 /api/docs 또는 /swagger 주소로 접속하면 볼 수 있다.
Swagger가 뭘 보여주나? 전체 API 목록을 확인 할 수 있다. GET, POST, PUT, DELETE 다 구분되어 있어 편리하게 확인이 가능하다.
각 API를 클릭하면 상세 정보가 펼쳐진다.
어떤 파라미터 필요한지 (필수인지 선택인지)
Request Body 예시 (JSON 형식)
Response 예시 (성공했을 때, 실패했을 때)
에러 코드 목록 (400, 401, 404, 500 등)
더 강력한건 "Try it out" 버튼이다. 브라우저에서 바로 API를 테스트할 수 있는데 파라미터 입력하고 Execute 누르면 실제로 호출된 결과 값을 확인 할 수 있다. 응답이 어떻게 오는지 눈으로 확인할 수 있기 때문에 코딩 들어가기전에 먼저 테스트해보면 큰 도움이 된다.
Postman Collection
Postman은 API 테스트 도구이다. 회사에서 Postman Collection을 공유하는 경우가 많다. 팀에서 미리 만들어둔 API 요청 모음집이다. 어디서 받나? 사내 위키에 링크가 있거나, Slack 채널 고정 메시지에 있거나, 동료에게 물어보자.
해당 파일을 얻으면 Postman에서 Import만 하면 끝. 그러면 모든 API 요청이 폴더별로 정리된다.
User API, Order API, Payment API... 이런 식으로.
각 요청을 열면 URL, Header, Body가 다 채워져 있다. Send 버튼만 누르면 바로 테스트할 수 있다.
특히 좋은 점은 환경 변수 기능이다. 개발 서버용, 운영 서버용 설정을 전환할 수 있다. 한 번 설정해두면 서버 주소 바꾸는 것도 클릭 한 번으로 가능하다.
회원가입 API를 구현하는 업무를 맡은 적이 있다. 프론트엔드에서 백엔드 API를 호출하는 부분.
어떤 데이터를 보내야 하는지 몰랐다. 동료가 "Swagger 보면 돼" 라고 했거 접속하니 API 목록이 죽 나왔다.
"POST /api/auth/signup" 클릭 Request Body 예시가 나왔다.
{
"email": "user@example.com",
"password": "password123",
"name": "홍길동",
"phoneNumber": "010-1234-5678"
}
'아하 4개 필드를 보내면 되는구나.' Response 클릭 해보니
{
"userId": 123,
"email": "user@example.com"
}
'성공하면 userId를 받는구나'
에러 응답도 나와 있었다.
400: 이메일 형식 오류
409: 이미 존재하는 이메일
이렇게 포스트맨 설정 파일 하나면 신입이 하나하나 삽질하며 알아낼 필요가 없다. 어떤 Header를 써야 하는지, Body 형식은 어떻게 되는지, 인증 토큰은 어디에 넣어야 하는지, 환경별로 서버 주소는 어떻게 바꾸는지. 선배들이 수개월에 걸쳐 시행착오를 겪으며 쌓아온 모든 노하우가 그 파일 안에 담겨 있다. Import 한 번으로 그 모든 걸 물려받을 수 있다.
도메인 용어 정리
회사마다 특이한 용어가 있다. 업계 용어도 있고, 회사 내부에서만 쓰는 용어가 있다. 신입한테는 정말 그대로 외계어로 느껴진다.
도메인 용어란?
업계나 서비스 특유의 전문 용어을 말한다.
예를 들어 금융권에 가면 "FDS", "PG", "BEP" 이런 약자들이 튀어나오고. 이커머스는 "SKU", "GMV", "MAU". 배달앱은 "라이더", "픽업존", "콜배차".
처음 듣는 사람은 무슨 말인지 모르는게 당연하다. 하지만 회사 사람들은 일상처럼 쓴다. 특히 회의에서 이런 용어가 막 나오면 난감할 수 밖에 없다.
용어 정리 문서 찾기
대부분의 회사는 용어집이 있다.
사내 위키에 "용어집", "Glossary", "도메인 용어" 같은 제목으로 검색해보자. 신입 온보딩 문서에 링크가 있는 경우도 있다. 이런 없다고? 그럼 직접 만들어 보자. 입사 후 2주일 정도 지나면 용어가 어느 정도 익는다. 그때 노션 페이지 하나 만들어서 정리하고 "우리 팀 용어 정리하면 어떨까요?" 제안해보는건 어떨까?
신입사원이 회사 용어 모르는 건 부끄러운 게 아니다. 지극히 당연한 거다. 회의 중에 모르는 용어 나왔는데 못 알아들은 척하고 넘어가면? 나중에 더 큰 문제가 생긴다. 그 용어 기준으로 업무 지시가 떨어지는데 모르고 있으면 더 큰 창피를 경험할 수 있다.
모르는 단어를 열심히 적어서 회의 끝나고 동료한테 물어보자. "아까 FDS가 뭐예요?" 이렇게 질문만 하면 된다. 혹은 회사 메신저에서 검색해보는 방법도 좋다. 과거 대화 기록에 맥락으로 확인이 가능하다.
실전 팁
입사 첫 주에 용어 정리 문서 찾아서 북마크하고, 영어 단어 외우듯 자주 펼쳐서 보자. 다 외워야 할 단어들이다.
문서가 없거나 오래됐다면?
규모가 작은 중소기업일 경우 문서가 아예 없는 경우도 태반이다. 있어도 부정확한 정보로 아무도 열어보지 않는 영양가 없는 문서만 있다면 이렇게 대처하보자
문서와 코드가 다를 때
우선 코드를 믿어라 문서는 업데이트를 안 했을 수 있다. 하지만 코드는 실제로 돌아가기 때메 거짓말을 안 한다. 문서는 참고만 하고, 최종 확인은 코드로 하자.
문서가 아예 없을 때
테스트 코드를 확인하자 테스트 코드는 살아있는 문서다. 함수를 어떻게 쓰는지, 어떤 값을 넣으면 어떤 결과가 나오는지 예시가 다 나와 있다.
또는 프로젝트 내에서 그 함수를 쓰는 다른 곳을 찾아보자. 실제 사용한 예시를 확인 가능하다.
디버거를 돌려보는 것도 좋다. 직접 실행하면서 파라미터에 뭐 들어가는지, 리턴값이 뭔지 눈으로 확인하자.
그리고 이해했으면 주석으로 남기자.
체크리스트: 문서 활용 준비
인라인 문서
함수 쓰기 전에 마우스 오버하는 습관
IDE 단축키 익히기 (VSCode: 마우스 오버, IntelliJ: Ctrl+Q)
API 문서
Swagger 주소 찾아서 북마크 (/api/docs 등)
Postman Collection 받아서 Import
API 작업 전에 문서부터 보는 습관
도메인 용어
용어 정리 문서 찾아서 북마크
모르는 용어 나올 때마다 바로 검색
없으면 동료에게 물어보기
문서 없을 때
테스트 코드 위치 파악
Find References 기능 익히기
디버거 사용법 익히기
문서는 지도다
코드는 미로고 복잡하고 길을 잃기 쉽다. 문서는 그 미로의 지도인 셈이다.
인라인 문서는 함수의 입구와 출구를 알려준다. API 문서는 서버와 대화하는 법을 알려준다.
용어 정리는 외계어를 번역해준다. 물론 문서가 항상 완벽하진 않다. 오래됐거나, 틀렸거나, 아예 없거나.
그래도 괜찮다. 없으면 코드를 보면 되고, 테스트 코드를 보면 되고, 동료에게 물어보면 된다.
문서를 보는 걸 습관으로 만들자. 문서 활용법을 익혔다면, 이제 다음 단계다.