JSDoc @depreacted 태그로 점진적 개선해보기

lee.byonghun

2024.04.24

JSDoc에는 여러 어노테이션이 있는데 그중에 @depreacted라는 어노테이션을 사용하여 이전에 사용하던 코드를 점진적으로 개선한 버전의 코드로 넘어가보았는데 유용한 것 같아 공유합니다.

배경 | 타입 관리

프론트엔드의 경우 백엔드의 API에 강한 의존성을 가지게 됩니다. 레스폰스의 타입을 백엔드에서 사용하는 그대로 사용해야 실수하지 않겠죠.

기존 프로젝트에서 이러한 타입 관리를 API를 정의해둔 파일에서 API의 타입도 같이 관리해왔습니다.

처음에는 실제 API를 사용하는 곳과 API의 타입이 가깝게 있어 알기 쉽고 관리에도 불편하지 않았습니다.

하지만, 점차 API가 많아지면서 API에서 비슷한 레스폰스들이 오는 경우들이 생기다 보니, 타입을 재사용하는 경우가 늘었습니다.

그러다보니 새로운 API를 추가하는 경우 기존에 타입이 정의되어있는지 확인을 놓쳐, 타입을 새롭게 추가하다 보니 여러 컴포넌트에서 같거나 비슷한 타입을 각기 다른 파일들에서 컴포넌트마다 다양한 방식으로 임포트하게되는 상황이 되었습니다.

또한, 이렇게 추가되고 변경되는 타입들이 여러 파일에 얽히고 설켜 실제 타입과도 괴리가 생기는등 관리가 어려워지게 됩니다.

점점 타입이 관리가 안되는 문제성을 깨닫고 API의 타입들을 한곳으로 몰아 중앙집중적으로 관리하도록 변경하려고 했습니다.

타입을 한곳에서 관리하는 파일을 만들고 새롭게 타입을 관리하려했지만, 기존에 컴포넌트들이 임포트 해오던 타입을 모두 새로운 타입으로 바라보게 바꾸려하였습니다.

타입대로라면 문제가 없겠지만, 동작 확인을 포함하면 영향 범위가 너무 커서 점진적으로 변경하고 싶게 됩니다.

자바스크립트에 주석을 달아서 문서처럼 사용할 수 있는 JSDoc이라는 시스템이 있습니다. 그 중에 @deprecated 라는 태그는 태그를 단 코드의 사용 중지를 알릴 수 있게 되어 앞으로의 사용을 방지 할 수 있습니다.

JSDoc은 타입스크립트에서도 사용가능하기에, 예를 들면 아래와 같이 기존에 쓰던 타입에 @deprecated를 달고 조금씩 새로운 타입으로 변경하는 방법이 있습니다.

/**
 * @deprecated `src/apis`의 타입을 사용해주세요.
 * */
export type OldType = API.NewType;

위의 주석처럼 태그를 달고 설명을 추가하게 되면 IDE의 익스텐션이나 설정등을 통해서 아래와 같이 보이게 됩니다.

- neovim

사용을 완전하게 막지는 않지만, 조금씩 변경해나가는 경우에 다른 개발자들에게 더 이상의 사용을 중지하고 새로운 방법을 사용하도록 제시할 수 있습니다.

JSDoc은 위와 같은 케이스말고도 여러가지 유용한 기능들을 많이 제공해서 조금은 알아두면 유용한 경우가 많습니다.

물론, JSDoc이 보이지 않는 상황이 있기도 합니다.

@deprecated를 사용할 순간이 오지않게 처음 부터 잘 만들어 두면 좋겠지만 어쩔 수 없이 코드 구조의 개선이나 사양의 개선이 이루어져야 한다면 써야 하는 순간이 오는 것 같습니다.

점진적으로 적용을 하는 것이다 보니 완벽하게 사용을 막으려면 다른 방법을 사용해야 하지만, 약간의 주의 정도를 제시하고 싶다면 이 방법을 고려해보는 것도 좋을 것 같습니다. 🤗