Legacy Code와 함께하는 jsDoc 사용의 이점 및 실용성

2024-10-28 08:13:34

javascripttypescriptjsdocwebdev

jsDoc의 장점 이해하기

많은 소프트웨어 개발자들이 유산(legacy) 코드베이스와 작업을 하며, TypeScript의 대안으로 jsDoc을 선택하는 경우가 많습니다. 본 블로그에서는 이렇게 jsDoc을 사용하게 되는 이유와 함께, 실제로 활용할 수 있는 방법들을 살펴보겠습니다. 또한 jsDoc과 TypeScript 간의 호환성에 대해서도 분석해보겠습니다.

jsDoc의 기본 이해

jsDoc은 자바스크립트 코드에서 주석을 통해 타입 정보를 제공하는 방법입니다. 이를 통해 개발자는 팀원들과 코드의 의미를 공유하고 문서화할 수 있습니다. jsDoc을 사용하면 코드의 작성 및 유지 보수가 용이해지며, 특히 대규모 프로젝트에서 유용합니다. 다음은 jsDoc의 기본 사용 예시입니다.

/** @typedef { 'JS' | 'JQuery' | 'TS' | 'jsDoc' } Phase; */

/**
 * @type {Phase}
 */
const goodCase = 'JQuery';

위의 코드에서, Phase라는 사용자 정의 타입을 정의하고 있습니다. 이는 goodCase 변수가 이 타입의 값을 가져야 한다는 것을 나타냅니다.

jsDoc과 TypeScript 비교

컴파일러의 필요성

jsDoc의 가장 큰 장점 중 하나는 코드 컴파일이 필요 없다는 것입니다. 자연스럽게 자바스크립트 파일에서 jsDoc 주석을 추가하여 사용이 가능합니다. 반면, TypeScript는 반드시 컴파일 과정을 거쳐야 합니다. 이는 jsDoc이 기존 자바스크립트 코드와 더 긴밀하게 호환되는 이유 중 하나입니다.

의존성 문제

jsDoc은 별도의 의존성을 필요로 하지 않습니다. 반면에 TypeScript는 컴파일러와 도구들을 설치해야 하기 때문에 환경 설정에 시간이 더 걸릴 수 있습니다. 특히 레거시 프로젝트에서는 이러한 점이 큰 장점으로 작용합니다.

넓은 호환성

jsDoc은 JavaScript 주석 시스템을 사용하기 때문에 다양한 플랫폼과 환경에서 활용할 수 있습니다. 코드와 주석이 함께 존재하므로, 다른 개발자들이 코드를 빠르게 이해할 수 있도록 돕습니다. TypeScript는 이러한 측면에서 상대적으로 인증된 환경 내에서만 작동해야 하는 제약이 있어 불편할 수 있습니다.

jsDoc 사용 경험

jsDoc을 사용할 수 있는 다양한 편집기도 있지만, 모든 편집기가 이를 지원하지는 않습니다. 특히, jsDoc을 다루는 데 익숙하지 않은 편집기에서는 주석의 의미가 충분히 전달되지 않을 수 있습니다. 하지만 VS Code와 같은 도구에서는 jsDoc의 타입 정보를 쉽게 시각화할 수 있기 때문에 추천할 만합니다.

npm 패키지에서의 jsDoc 활용

우리는 jsDoc을 사용하는 npm 모듈을 만들 수 있습니다. 이를 통해 TypeScript 없이도 jsDoc을 코드에 통합할 수 있습니다. 이러한 방식은 레거시 코드에서 새로운 의존성을 추가하지 않고도 기능을 향상시킬 수 있는 장점을 제공합니다.

export const useDuck = (reducer, initialState, labels) => {
  const [state, dispatch] = useReducer(reducer, initialState);
  const quack = useMemo(
    () => quackFactory(labels, dispatch),
    [dispatch, labels]
  );
  return [state, quack];
};

위의 코드는 패키지를 사용하는 다른 라이브러리와의 호환성을 높이기 위해 jsDoc을 사용하여 각 타입을 명확히 했습니다.

jsDoc과 TypeScript 간의 연결

jsDoc과 TypeScript는 서로 호환 가능합니다. jsDoc에서 정의한 타입 정보를 TypeScript에서도 사용할 수 있으며, 그 반대도 가능합니다. 이는 개발자가 jsDoc으로 시작했다가 후에 TypeScript로의 마이그레이션을 쉽게 할 수 있도록 돕습니다.

코드의 가독성과 유지 관리

jsDoc을 통해 코드의 가독성과 유지 관리의 효율성이 크게 개선될 수 있습니다. 주석을 통해 함수를 어떤 용도로 사용하는지, 각 변수의 타입이 무엇인지 명확하게 설명할 수 있기 때문입니다. 이는 팀 내 커뮤니케이션을 원활하게 하고, 새로운 팀원이 코드에 빠르게 적응할 수 있도록 돕습니다.

jsDoc 활용 팁

주석 미리 보기: VS Code를 사용하는 경우, 작성 중인 jsDoc 주석의 내용을 실시간으로 미리 볼 수 있는 기능을 활용하세요.
예시 사용: 코드의 주석에 예시를 추가하면, 다른 개발자들이 코드의 사용법을 이해하는 데 더욱 도움을 줄 수 있습니다.

결론

jsDoc은 Legacy Code베이스에서 TypeScript의 대안으로 강력한 도구입니다. 특유의 유연성과 편리함 덕분에 여러 개발 환경에서 효과적으로 사용될 수 있습니다. 따라서, 오랜 기간 유지보수가 필요한 코드베이스에서 jsDoc은 충분히 주목할 만한 선택이 될 수 있습니다.

참고 자료

위 자료들을 통해 jsDoc의 활용 방법과 이점을 깊이 있게 알아볼 수 있습니다. 또한 다른 개발자들과 jsDoc의 효과적인 사용에 대해 논의할 수 있는 기회도 마련할 수 있습니다. Happy coding!