회사를 입사하기 전 원티드에서 진행하는 타입스크립트 교육을 들었다.
교육 중에 JSDoc을 작성하는 법을 알려줬고, 그 때는 ‘음 쓰면 편하겠네’ 정도로 생각했는데
막상 회사코드의 util 폴더에서 원하는 함수를 찾다보면 ‘아 써야겠다’로 바꼈다.
JSDoc에 대해 처음들어봤고 뭔지 궁금하다면 poiemaweb를 참고하면 좋다.
JSDoc는 자바스크립트 코드에서 사용하는 주석으로, 코드의 가독성과 이해를 돕기 위해 작성한다.
일반 주석과 JSDoc의 다른점은 함수, 변수, 클래스 등의 역할과 사용법에 대한 정보를 작성한다는 것이다.
JSDoc 주석은 일반적으로 /** 와 */ 사이에 위치하며, 함수와 클래스 정의 위에 작성된다.
함수에 사용한다면,
이 함수가 어떤 기능의 함수인지, 사용할 때 주의할 부분은 없는지, 어떤 매개변수(@param)를 전달해야하는지, 그리고 리턴값(@returns)을 어떤 값이 오는지에 대해 설명을 붙일 수 있다.
/**
* 중첩된 두 객체를 비교하고 동일한 키에 대해 서로 다른 값이 있는지 확인한다.
* (한 쪽만 가지고 있는 키에 대해선 비교하지 않는다.)
* @param {Object} obj1
* @param {Object} obj2
* @returns {boolean} 객체가 동일한 키에 대해 다른 값을 가지고 있으면 true를 반환하고, 그렇지 않으면 false를 반환한다.
*/
hasDifferentValues: function (obj1, obj2) {
function traverse(obj1, obj2) {
for (let key in obj1) {
if (obj1.hasOwnProperty(key) && obj2.hasOwnProperty(key)) {
if (typeof obj1[key] === 'object' && typeof obj2[key] === 'object') {
if (traverse(obj1[key], obj2[key])) {
return true;
}
} else if (obj1[key] != obj2[key] && !(obj1[key] === null && obj2[key] === '')) {
return true;
}
}
}
return false;
}
return traverse(obj1, obj2);
},그리고 JSDoc을 작성하면 개발자 도구에서 API 문서를 자동으로 생성해 보여준기 때문에 생산성을 높일 수 있다.
위와 같이 정의하면 ide에서 JSDoc를 지원한다.
ide가 자동으로 API문서를 생성해 사용하는 함수에 대한 정보도 보여준다.
매개변수를 어떻게 줘야하는지 생각이 안난다면 코드 위에 마우스 커서만 올려주면 된다.
코드만 작성되어 있는 경우 어떤 함수인지 파악하기 힘들다.
그리고 수 많은 함수 중 내가 원하는 함수를 찾는데 소비하는 시간보다
만들어서 추가하는 편이 더 편하고 빠르지 않을까 고민하게 된다.
하지만 동일한 기능을 하는 함수를 만들 경우
중복 코드가 발생하고, 유지보수가 어렵기 때문에 지양해야 한다.
여러 사람들이 작업한다면 함수에 대한 기능을 정확히 적어
무슨 함수인지 파악하는 시간을 줄여주는 것도 애자일한 개발이구나 싶었다.
물론 잘못된 설명이라면 없느니만 못하니
코드도 꾸준히 리팩토링해주는 것처럼 JSDoc도 리팩토링하는 습관을 들여야겠다.
