주석
코드 구조에서 알아본 바와 같이 한 줄짜리 주석은 //로, 여러 줄의 주석은 / ... /의 형태로 사용한다.
주석(comment)은 어떻게 코드가 동작하는지, 왜 코드가 동작하는지를 설명하는 데 쓰인다.
주석 작성은 쉬워 보이지만, 초보 개발자는 종종 잘못된 방법으로 작성하는 실수를 범한다.
좋지 않은 주석
'코드에서 무슨 일이 일어나는지’에 대한 내용이 담긴 주석
// 이 코드는 (...)과 (...)을 수행합니다
// A라는 개발자가 이 기능에 대해 알고 있으며...
very;
complex;
code;좋은 방법이 아니다. 좋은 코드엔 ‘설명이 담긴(explanatory)’ 주석이 많아선 안 된다. 주석 없이 코드 자체만으로 코드가 무슨 일을 하는지 쉽게 이해할 수 있어야 한다.
이와 관련된 좋은 규칙도 있다. “코드가 불분명해서 주석 작성이 불가피하다면 코드를 다시 작성해야 하는 지경에 이른 걸 수 있다.”
리팩토링 팁: 함수 분리하기
함수 내 코드 일부를 새로운 함수로 옮기는 게 유익할 때가 있다.
function showPrimes(n) {
nextPrime:
for (let i = 2; i < n; i++) {
// i가 소수인지를 확인함
for (let j = 2; j < i; j++) {
if (i % j == 0) continue nextPrime;
}
alert(i);
}
}코드 일부를 함수 isPrime으로 옮기면 더 나은 코드를 작성할 수 있습니다.
function showPrimes(n) {
for (let i = 2; i < n; i++) {
if (!isPrime(i)) continue;
alert(i);
}
}
function isPrime(n) {
for (let i = 2; i < n; i++) {
if (n % i == 0) return false;
}
return true;
}함수 이름 자체가 주석 역할(함수명과 매개변수명에 의해)을 하므로 코드를 쉽게 이해할 수 있다. 이런 코드를 자기 설명적인(self-descriptive) 코드라 부른다.
리팩토링 팁: 함수 만들기
아래와 같이 코드가 ‘아래로 죽 늘어져 있는’ 경우
// 위스키를 더해줌
for(let i = 0; i < 10; i++) {
let drop = getWhiskey();
smell(drop);
add(drop, glass);
}
// 주스를 더해줌
for(let t = 0; t < 3; t++) {
let tomato = getTomato();
examine(tomato);
let juice = press(tomato);
add(juice, glass);
}
// ...이럴 땐 새로운 함수를 만들고, 코드 일부를 새로 만든 함수에 옮기는 게 좋다.
addWhiskey(glass);
addJuice(glass);
function addWhiskey(container) {
for(let i = 0; i < 10; i++) {
let drop = getWhiskey();
//...
}
}
function addJuice(container) {
for(let t = 0; t < 3; t++) {
let tomato = getTomato();
//...
}
}함수는 주석이 없어도 그 존재 자체가 무슨 역할을 하는지 설명할 수 있어야 한다. 코드를 분리해 작성하면 더 나은 코드 구조가 된다. 이런 가이드를 잘 지켜 코드를 작성하면 함수가 어떤 동작을 하는지, 무엇을 받고 무엇을 반환하는지가 명확해진다.(실무에서 특수한 상황일 경우는 예외)
좋은 주석
아키텍처를 설명하는 주석
고차원 수준 컴포넌트 개요, 컴포넌트 간 상호작용에 대한 설명, 상황에 따른 제어 흐름 등은 주석에 넣는 게 좋다. 조감도 역할을 해주기 때문이다. 고차원 수준의 아키텍처 다이어그램을 그리는 데 쓰이는 언어인 UML도 시간을 내어 공부해 보면 도움이 될 것이다.
함수 용례와 매개변수 정보를 담고 있는 주석
JSDoc이라는 특별한 문법을 사용하면 함수에 관한 문서를 쉽게 작성할 수 있다. 여기엔 함수 용례, 매개변수, 반환 값 정보가 들어간다.
/**
* x를 n번 곱한 수를 반환함
*
* @param {number} x 거듭제곱할 숫자
* @param {number} n 곱할 횟수, 반드시 자연수여야 함
* @return {number} x의 n 거듭제곱을 반환함
*/
function pow(x, n) {
...
}이렇게 주석을 달면 코드를 읽어보지 않고도 함수의 목적과 사용법을 한눈에 알 수 있다.
WebStorm 등의 다양한 에디터는 이런 주석을 이용해 자동 완성 기능, 자동 에러 검출 기능 등을 제공한다.
JSDoc 3이나 기타 유사한 툴을 사용하면 주석으로 HTML 문서를 만들 수 있습니다. 자세한 정보는 http://usejsdoc.org/에서 확인할 수 있다.
왜 이런 방법으로 문제를 해결했는지를 설명하는 주석
코드를 최적의 방법으로 작성했을 때 미묘한 문제가 생기는 경우가 있다. 이러한 경우 차선의 방법을 선택하기 마련인데, 그 미묘한 문제, 즉 차선의 방법을 선택한 이유에 대해 설명하는 주석은 해당 함수를 리팩토링하는 과정에서 동료 개발자 또는 스스로가 같은 문제를 마주하는 것일 방지한다. 왜 이런 식으로 코드를 작성했는지에 대한 이유가 명확하지 않을 경우, 코드를 더욱 효율적으로 리팩토링하는 과정에서 이전에 겪었던 동일한 문제를 다시 만날 수 있기 때문이다.
직감에 반하는 미묘한 동작을 수행하는 코드가 있다면 주석을 달아주는 게 좋다.
요약
- 주석을 잘 작성하면 나중에 코드를 다시 볼 때 효율적으로 정보를 얻을 수 있다.
- 주석에 들어가면 좋은 내용
- 고차원 수준 아키텍처
- 함수 용례
- 당장 봐선 명확해 보이지 않는 해결 방법에 대한 설명
- 주석에 들어가면 좋지 않은 내용
- '코드가 어떻게 동작하는지’와 '코드가 무엇을 하는지’에 대한 설명
- 코드를 간결하게 짤 수 없는 상황 또는 코드 자체만으로도 어떤 일을 하는지 충분히 판단할 수 없는 경우는 주석을 넣자
- '코드가 어떻게 동작하는지’와 '코드가 무엇을 하는지’에 대한 설명
- 주석은 JSDoc3 같은 자동 문서생성 도구에도 쓰인다. 자동 문서생성 도구는 주석을 이용해 HTML 등의 포맷을 가진 문서를 자동으로 만들어준다.
