배경
코드가 길어지다보면 내가 만든 메서드임에도 어떤 매개변수를 넣어야하는지 헷갈리는 경우가 종종 발생한다. 그때마다 매번 정의한 위치를 찾아가서 보는 것은 너무나 불편하게 느껴졌다.
때로는 잘못된 타입의 매개변수를 입력해서 런타임 에러가 발생하거나 혹은 의도하지 않은 결과가 나타나는 것이 너무 마음에 안들었다.
이런 문제를 만나면 디버깅하는 것이 너무나 성가시고 귀찮다.
JSDoc을 활용하면 자바스크립트 소스코드에 타입에 대한 힌트를 제공할 수 있으며, 내가 작성한 메서드에 대한 자세한 주석을 마우스 오버하는 것으로 코드 어디에서든 쉽게 확인할 수 있다.
JSDoc은 자바스크립트 소스 코드 파일들에 주해를 달기 위해 사용하는 마크업 언어이다. JSDoc을 포함하는 주석을 사용하는 프로그래머들은 자신들이 작성하는 코드의 API를 설명하는 설명 문서를 추가할 수 있다. 그 뒤 다양한 도구들에 의해 처리되어 HTML과 리치 텍스트 포맷 등의 접근 가능한 포맷으로 문서가 생성된다. — 위키백과: JSDoc
JSDoc 사용방법
- 사용방법은 매우 심플하다. /**를 입력하고 주석을 작성할 수 있다.
/**
*
* @param {*} name
* @param {*} age
*/
function Person(name, age) {
return `내 이름은 ${name}입니다. 올해로 ${age}살입니다.`
}@param, @returns은 무엇입니까?
@param은 함수의 매개변수를 설명하는 키워드{}안에는 매개변수의 타입을 적어줍니다.@returns은 함수의 리턴값에 대한 설명을 위한 키워드
@param에 type을 지정해 놓으면 엄청난 장점이 있습니다. 그건 바로 VSCode가 해당 타입에 맞는 메서드를 자동으로 추천해줄 수 있기 때문입니다.
많이 사용하는 키워드
- 해당 메서드의 버전, 참조 링크(
@version,@see) - 읽기 전용이니 수정하지 말아달라는 키워드, 해당 값이 const 즉 상수라는 것임을 알려주는 키워드(
@readonly,@const) - 주석에 메모를 작성해 둘 수 있습니다. 앞으로 해야할 작업 등 (
@todo) - 이 키워드는 주석을 단 메서드나 변수가 더이상 사용되지 않음을 의미합니다.(
@deprecated) - 변수의 타입을 적어줄 수 있는 키워드입니다. (
@type)
마무리
JSDoc은 자바스크립트 소스 코드 파일들에 주해를 달기 위해 사용하는 마크업 언어다.
메서드(함수) 뿐만 아니라, 변수, 객체 등에도 작성할 수 있다.
JSDoc는 강제성이 없다. 함수나 변수를 사용하는 사람에게 힌트를 제공할 뿐입니다. (typescript와의 차이점)
주석이 필요 없을 만큼 코드를 읽기 좋게 작성하는 것이 좋겠지만, 문서화 작업은 협업과 유지 보수를 위해 필수적인 작업입니다.
참조
JSDoc에 대해서 보다 자세하게 알아보려면 Use JSDoc을 참조하면 좋습니다.
JSDoc을 사용하여 자바스크립트에 타입 힌트 제공하기를 참조하면 js파일에서 타입 힌트를 작성하고 체크하는 방법을 확인할 수 있습니다.
