JavaScript는 type이 불명확하므로 문서화를 통해 그 상세정보를 남겨야 합니다. 그러나 소스코드와 분리된 문서는 사실상 그 활용가치가 매우 떨어집니다. 소스코드와 일원화된 방식으로 문서화가 되어야 하는데, 바로 주석입니다. 아래는 어떤 클래스의 특정함수에 대한 주석을 통한 문서화에 대한 간단한 예시입니다. /** * 메뉴 항목을 추가한다. * @param {string} id 항목에 대한 고유 식별자 * @param {string} url 항목 아이콘 * @param {string} title 항목 타이틀 * @param {function} callback 실행에 대한 호출 함수 * @returns {boolean} 성공 여부 */ addMenu(id, url, title, callback) { ... IDE는 이 주석을 실시간으로 해석해 개발자에게 매우 직관적인 힌트를 제공합니다. 예를들어서 VSCode에서는 아래와 같은 힌트를 제공합니다. 아울러 이러한 주석은 다양한 문서 형식으로써, 예를들어 pdf, docx, html 등과 같은 별도의 문서를 자동으로 생성해 낼 수 있습니다. 코드 구조에서 알아본 바와 같이 한 줄짜리 주석은 주석(comment)은 어떻게 코드가 동작하는지, 왜 코드가 동작하는지를 설명하는 데 쓰입니다. 주석을 작성하는 게 쉬워 보일 수 있는데, 초보 개발자들은 종종 잘못된 방법으로 주석을 작성하는 실수를 범합니다. 좋지 않은 주석초심자들은 주석에 '코드에서 무슨 일이 일어나는지’에 대한 내용을 적곤 합니다. 아래와 같이 말이죠.
그러나 좋은 코드엔 ‘설명이 담긴(explanatory)’ 주석이 많아선 안 됩니다. 주석 없이 코드 자체만으로 코드가 무슨 일을 하는지 쉽게 이해할 수 있어야 합니다. 이와 관련된 좋은 규칙도 있습니다. “코드가 불분명해서 주석 작성이 불가피하다면 코드를 다시 작성해야 하는 지경에 이른 걸 수 있습니다.” 리팩토링 팁: 함수 분리하기함수 내 코드 일부를 새로운 함수로 옮기는 게 유익할 때도 있습니다. 아래와 같이 말이죠.
코드 일부를 함수
함수 이름 자체가 주석 역할을 하므로 코드를 쉽게 이해할 수 있게 되었습니다. 이런 코드를 자기 설명적인(self-descriptive) 코드라 부릅니다. 리팩토링 팁: 함수 만들기아래와 같이 코드가 ‘아래로 죽 늘어져 있는’ 경우를 생각해 봅시다.
이럴 땐 새로운 함수를 만들고, 코드 일부를 새로 만든 함수에 옮기는 게 좋습니다. 아래와 같이 말이죠.
함수는 주석이 없어도 그 존재 자체가 무슨 역할을 하는지 설명할 수 있어야 합니다. 코드를 분리해 작성하면 더 나은 코드 구조가 되죠. 이런 가이드를 잘 지켜 코드를 작성하면 함수가 어떤 동작을 하는지, 무엇을 받고 무엇을 반환하는지가 명확해집니다. 그런데 실무에선, ‘설명이 담긴’ 주석을 작성하는 게 불가피한 경우도 있습니다. 알고리즘이 복잡한 코드를 작성하는 경우나 최적화를 위해 코드를 약간 비틀어 작성할 땐 설명을 적어주어야 합니다. 이런 경우를 제외하곤 간결하고 코드 자체만으로 설명이 가능하게 코딩해야 합니다. 좋은 주석설명이 담긴 주석은 대개 좋지 않습니다. 그럼 좋은 주석이란 무엇일까요? 예시:
이렇게 주석을 달면 코드를 읽어보지 않고도 함수의 목적과 사용법을 한눈에 알 수 있습니다. WebStorm 등의 다양한 에디터는 이런 주석을 이용해 자동 완성 기능, 자동 에러 검출 기능 등을 제공합니다. JSDoc 3이나 기타 유사한 툴을 사용하면 주석으로 HTML 문서를 만들 수 있습니다. 자세한 정보는 http://usejsdoc.org/에서 확인하시기 바랍니다. 왜 이런 방법으로 문제를 해결했는지를 설명하는 주석무엇이 적혀있는지는 중요합니다. 그런데 무슨 일이 일어나고 있는지 파악하려면 무엇이 적혀있지 않은 지가 더 중요할 수 있습니다. '왜 이 문제를 이런 방법으로 해결했나?'라는 질문에 코드는 답을 해 줄 수 없기 때문입니다. 문제 해결 방법이 여러 가지인데 왜 하필이면 이 방법을 택했는지 의문이 들 때가 있습니다. 선택한 방법이 가장 나은 것도 아닌데 말이죠. 왜 이런 방법을 써서 문제를 해결했는지 알려주는 주석이 없으면 다음과 같은 일이 발생할 수 있습니다.
해결 방법을 담고 있는 주석은 아주 중요한 역할을 합니다. 이전에 했던 실수를 방지하는 안내판 역할을 하기 때문입니다. 미묘한 기능이 있고, 이 기능이 어디에 쓰이는지를 설명하는 주석직감에 반하는 미묘한 동작을 수행하는 코드가 있다면 주석을 달아주는 게 좋습니다. 요약주석을 보면 좋은 개발자인지 아닌지를 어느 정도 알 수 있습니다. 주석을 언제 쓰고 언제 쓰지 않는지를 보면 되죠. 주석을 잘 작성해 놓으면 시간이 지난 후 코드를 다시 살펴볼 때 효율적으로 정보를 얻을 수 있습니다. 코드 유지보수에 도움이 되죠. 주석에 들어가면 좋은 내용
주석에 들어가면 좋지 않은 내용
주석은 JSDoc3 같은 자동 문서생성 도구에도 쓰입니다. 자동 문서생성 도구는 주석을 이용해 HTML 등의 포맷을 가진 문서를 자동으로 만들어줍니다. |