오늘은 자바스크립트의 주석에 대해 좀 더 알아보겠습니다.
모던 자바스크립트 튜토리얼을 참고하였습니다.
좋지 않은 주석
때론 주석에 '코드에서 무슨 일이 일어나는지'에 대한 내용을 적곤한다.
그러나 좋은 코드엔 '설명이 담긴(explanatory)' 주석이 많아선 안된다. 주석 없이 코드 자체만으로 코드가 무슨 일을 하는지 쉽게 이해할 수 있어야한다.
이와 관련된 좋은 규칙도 있다. "코드가 불분명해서 주석 작성이 불가피하다면 코드를 다시 작성해야 하는 지경에 이른 걸 수 있다."
리팩토링 팁 : 함수 분리하기
함수 내 코드 일부를 새로운 함수로 옮기는 게 유익할 때도 있다.
코드 일부를 함수 isPrime으로 옮기면 더 나은 코드를 작성할 수 있다.
함수 이름 자체가 주석 역할을 하므로 코드를 쉽게 이해할 수 있게 되었다. 이런 코드를 자기 설명적인(self-decriptive) 코드라 부른다.
리팩토링 팁 : 함수 만들기
아래와 같이 코드가 '아래로 축 늘어져 있는' 경우를 생각해 보자.
이럴 땐 새로운 함수를 만들고, 코드 일부를 새로 만든 함수에 옮기는게 좋다.
함수는 주석이 없어도 그 존재 자체가 무슨 역할을 하는지 설명할 수 있어야한다. 코드를 분리해 작성하면 더 나은 코드 구조가 된다. 이런 가이드를 잘 지켜 코드를 작성하면 함수가 어떤 동작을 하는지, 무엇을 받고 무엇을 반환하는지가 명확해진다.
그런데 실무에선, '설명이 담긴' 주석을 작성하는게 불가피한 경우도 있다. 알고리즘이 복잡한 코드를 작성하는 경우나 최소화를 위해 코드를 약간 비틀어 작성할 땐 설명을 적어주어야한다. 이런 경우를 제외하곤 간결하고 코드 자체만으로 설명이 가능하게 코딩해야한다.
좋은 주석
**아키텍쳐를 설명하는 주석** 고차원 수준 컴포넌트 개요, 컴포넌트 간 상호작용에 대한 설명, 상황에 따른 제어 흐름 등은 주석에 넣는게 좋다. 이런 주석은 조감도 역할을 해준다. 고차원 수준의 아키텍쳐 다이어그램을 그리는데 쓰이는 언어인 UML도 시간을 내어 공부해 보자.함수 용례와 매개변수 정보를 담고 있는 주석
JSDoc이라는 특별한 문법을 사용하면 함수에 관한 문서를 쉽게 작성할 수 있다. 여기엔 함수 용례, 매개변수, 반환 값 정보가 들어간다.
이렇게 주석을 달면 코드를 읽어보지 않고도 함수의 목적과 사용법을 한눈에 알 수 있다.
WebStorm 등의 다양한 에디터는 이런 주석을 이용해 자동 완성 기능, 자동 에러 검출 기능 등을 제공한다.
JSDoc 3이나 기타 유사한 툴을 사용하면 주석으로 HTML 문서를 만들 수 있다.
왜 이런 방법으로 문제를 해결했는지를 설명하는 주석
무엇이 적혀있는지가 중요하다. 그런데 무슨 일이 일어나고 있는지 파악하려면 무엇이 적혀있지 않은 지가 더 중요할 수 있다. '왜 이 문제를 이런 방법으로 해결했나?"라는 질문에 코드는 답을 해 줄 수 없기 때문이다.
문제 해결 방법이 여러 가지인데 왜 하필이면 이 방법을 택했는지 의문이 들 때가 있다. 선택한 방법이 가장 나은 것도 아니긴하다.
미묘한 기능이 있고, 이 기능이 어디에 쓰이는지를 설명하는 주석
직감에 반하는 미묘한 동작을 수행하는 코드가 있다면 주석을 달아주는게 좋다.
