모던 JavaScript 튜토리얼을 읽고 정리하였습니다.
주석
코드 구조에서 알아본 바와 같이 한 줄짜리 주석은 //로, 여러 줄의 주석은 /* … */로 시작한다. 주석(comment)은 어떻게 코드가 동작하는지, 왜 코드가 동작하는지를 설명하는 데 쓰인다. 초보 개발자들은 종종 잘못되 방법으로 주석을 작성하는 실수를 범한다.
좋지 않은 주석
초심자들은 주석에 ‘코드에서 무슨 일이 일어나는지’에 대한 내용을 적곤 한다.
// 이 코드는 (...)과 (...)을 수행합니다
// A라는 개발자가 이 기능에 대해 알고 있으며...
very;
complex;
code;
그러나 좋은 코드에는 설명이 담긴 주석이 많아서는 안된다. 주석 없이 코드 자체만으로 코드가 무슨 일을 하는지 쉽게 이해가 가능해야 하기 때문이다. 코드가 불분명해서 주석 작성이 불가피하다면 코드를 다시 작성할 필요가 있는 걸 수도 있다.
리팩토링 팁 : 함수 분리하기
함수 내 코드 일부를 새로운 함수로 옮기는 게 유익할 때가 있다.
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);
}
}
다음 코드에서 I가 소수인지를 확인하는 코드를 새로운 메서드 isPrime으로 뽑아보면, 메서드명만으로 해당 코드 묶음이 무슨 일을 하는 지 바로 알 수가 있게 된다. 이런 코드를 자기 설명적인(self-descriptive) 코드라고 부른다.
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;
}
리팩토링 팁 : 함수 만들기
// 위스키를 더해줌
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);
}
// ...
위와 코드가 길게 늘어져있을 때에는 새로운 함수를 만들고, 코드 일부를 새로 만든 함수에 옮기는 편이 코드의 가독성을 높인다.
addWhiwkey(glass);
addJuice(glass);
function addWhiskey(container) {
for (let i = 0; i < 10; i++) {
let drop = getWhiskey();
// ...
}
}
function addJuice(container) {
for (let t = 0; i < 3; t++) {
let tomato = getTomato();
// ...
}
}
함수는 주석이 없어도 그 존재 자체가 무슨 역할을 하는지 설명할 수 있어야 한다. 코드를 잘 분리하고, 함수가 어떤 동작을 하는지 무엇을 받고 무엇을 반환하는지를 명확히 할수록 좋은 코드가 된다.
좋은 주석
아키텍쳐를 설명하는 주석
고차원 수준 컴포넌트 개요, 컴포넌트 간 상호작용에 대한 설명, 상황에 따른 제어 흐름 등은 주석에 넣는게 좋다. 고차원 수준의 아키텍쳐 다이어그램을 그리는데 쓰이는 언어인 UML도 공부를 해두면 좋다.
함수 용례와 매개변수 정보를 담고 있는 주석
JSDoc이라는 특별한 문법을 사용하면 함수에 관한 문서를 쉽게 작성할 수가 있다. 여기엔 함수 용례, 매개변수, 반환 값 정보가 들어간다.
/**
* x를 n번 곱한 수를 반환함
*
* @param {number} x 거듭제곱할 숫자
* @param {number} n 곱할 횟수, 반드시 자연수여야 함
* @return {number} x의 n 거듭제곱을 반환함
*/
function pow(x, n) {
...
}
WebStorm 등의 에디터는 이 주석을 갖고 자동완성 기능이나, 자동 에러 검출 기능 등을 제공하며, JSDoc3이나 기타 유사한 툴을 사용하면 이 주석을 통해 HTML 문서를 만들 수도 있다.
왜 이런 방법으로 문제를 해결했는지를 설명하는 주석
코드에서 무슨 일이 일어나고 있는지 파악하려면, 적혀있는 내용보다 적혀있지 않은 내용에 집중해야 한다. 예를 들어, ‘왜 이 문제를 이렇게 해결했는지’에 관한 답변은 코드를 통해 확인할 수 없다.
이 정보가 필요한 이유는 다음과 같다. 만약 왜 이 방법으로 문제를 해결했는지 알려주는 주석을 작성하지 않는다면, 코드를 작성한 후 시간이 꽤 흐르고 나면, 왜 그렇게 작성했는지 이유를 잊어버리고 더 불리한 코드로 바꿔서 똑같은 문제 해결 과정을 반복할 위험이 있기 때문이다. 이 때 주석은 이전에 했던 실수를 방지하는 안내판 같은 역할을 한다.
Comments