주석(comment)

한 줄 주석 : //

여러 줄 주석 : /* … */

 

주석을 사용하는 이유?

• 어떻게 코드가 동작하는지, 왜 코드가 동작하는지 설명하기 위해
• 코드 유지보수를 위해

 

좋지 않은 주석

• 설명이 담긴 주석이 많은 코드 ➡️ 주석 없이 코드만으로도 이해가 되어야 함
• 주석을 꼭 작성해야 하는 코드 ➡️ 코드를 다시 작성해야 할지도 모른다 

 

리팩토링 팁 : 함수 분리하기

• 함수 내 코드 일부를 새로운 함수로

function showPrimes(n) {
nextPrime:
for (let i = 2 ; i < n ; i++) {
for (let j = 2 ; j < i ; j++) {
if (i % j == 0) continue nextPrime;
}
console.log(i);
}
}

⬇️

function showPrimes(n) {

for (let i = 2 ; i < n ; i++) {
if (!isPrime(i)) continue;
console.log(i);
}
}

function isPrime(n) {
for (let i = 2 ; i < n ; i++) {
if (n % i == 0) return false;
}

return true;
}

 

이런 경우 함수 이름 자체가 - showPrimes, isPrime - 주석 역할을 한다

= 자기 설명적인 코드(self-descriptive code)

 

리팩토링 팁 : 함수 만들기

• 함수는 주석 없이 그 존재 자체가 무슨 역할을 하는지 설명할 수 있어야 한다
• 함수로 코드를 분리해 작성하면 무엇을 받고, 반환하는지가 명확해진다

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();
// …
}
}

 

좋은 주석

ㄴ architecture(건축학)을 설명하는 주석

 

• 고차원 수준 컴포넌트 개요/컴포넌트 간 상호작용/상황에 따른 제어흐름(O)
• 고차원 수준의 architecture 다이어그램을 그리는 언어(UML?)

 

ㄴ 함수 용례와 매개변수 정보를 담고 있는 주석

 

• JSDoc ➡️ 함수에 관한 문서 쉽게 작성(함수 용례, 매개변수, 반환 값 정보)

/**
 * x를 n번 곱한 수를 반환
 *
 * @param {number} x 거듭제곱할 숫자
 * @param {number} n 곱할 횟수, 반드시 자연수
 * @return {number} x의 n 거듭제곱을 반환
 */

function pow(x, n) {
…
}

 

ㄴ 문제 해결 방법 주석

• 왜 이 방법을 써서 해결했는지 주석을 써 놓으면, 과거의 여러가지 시도를 했던 것을 알고 시간 낭비를 하지 않을 수 있다 ➡️ 즉, 이전에 했던 실수를 방지할 수 있다

 

ㄴ 미묘한 기능이 있고 이 기능이 어디에 쓰이는지 설명하는 주석

 

 

 

• 주석을 언제 쓰고 안쓰고를 보면 좋은 개발자인지 알 수 있다

• 주석은 시간이 흐른 뒤 코드를 다시 살펴볼 때 효율적으로 정보를 얻을 수 있다

즉 코드 유지보수에 도움이 된다

• 주석에 들어가면 좋은 내용 : 위에 내용 + 간결하지 않은 코드나 코드만 봐서는 이해할 수 없는 경우에 작성

• 주석에 들어가지 않아도 될 내용 : 코드가 어떻게 동작하는지/코드가 무엇을 하는지

 

• UML, WebStorm, JSDoc : 자동 문서생성 도구(시간이 나면 알아보도록 하자)