22. 주석

주제: 주석(Comment) 작성의 예술 🎨

---

1. 주석이란 무엇인가요? 🤔

주석은 코드의 설명서입니다. 코드가 왜 이렇게 작성되었는지, 어떻게 동작하는지를 사람들에게 알려줍니다.
하지만, 주석은 신중히 작성해야 하며, **"필요하지 않은 곳엔 주석을 남기지 않는 것이 더 좋은 주석이다"**라는 철학도 중요합니다.

• 좋은 주석은 코드의 이해를 돕습니다.
• 나쁜 주석은 코드의 가독성을 망칩니다.

---

2. 나쁜 주석의 예 🛑

나쁜 주석은 "코드 자체가 이미 말해주는 내용을 반복"하거나 "불필요한 정보를 포함"합니다.

// 두 숫자를 더합니다
let sum = a + b;

🙅‍♀️ 왜 나쁜가요?
코드를 읽어 보면 a + b가 두 숫자를 더하는 것을 바로 알 수 있습니다. 이런 주석은 쓸모없어요!

---

3. 좋은 주석의 예 ✅

좋은 주석은 "코드로 쉽게 알 수 없는 내용"을 설명합니다. 특히 왜 이 코드가 작성되었는지를 알려주는 것이 중요합니다.

// 브라우저 호환성을 위해 이 polyfill을 추가합니다.
// 이 코드는 IE 11에서도 작동해야 합니다.
if (!Array.prototype.includes) {
  Array.prototype.includes = function (value) {
    return this.indexOf(value) !== -1;
  };
}

🧙‍♂️ 좋은 이유
왜 이 코드를 작성했는지 설명함으로써 나중에 이 코드가 필요한 이유를 이해할 수 있습니다.

---

4. 좋은 코드와 주석의 관계: 주석 없이도 이해되는 코드 작성하기 🎯

좋은 코드 자체가 주석 역할을 합니다. 함수 이름, 변수 이름을 잘 짓는 것만으로도 주석을 줄일 수 있습니다.

비교해봅시다:

나쁜 예:

// i가 소수인지 확인합니다
for (let i = 2; i < n; i++) {
  let isPrime = true;

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

  if (isPrime) alert(i);
}

좋은 예:

function showPrimes(n) {
  for (let i = 2; i < n; i++) {
    if (isPrime(i)) alert(i);
  }
}

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

• 함수 이름과 코드 자체가 설명을 대체합니다.
• 이렇게 작성된 코드를 자기 설명적인 코드라고 부릅니다.

---

5. 주석을 써야 하는 경우 📝

1. 복잡한 알고리즘
   • 복잡한 로직은 이해를 돕기 위해 주석을 추가합니다.

   // 다익스트라 알고리즘 구현
   function findShortestPath(graph, startNode, endNode) {
     // ...
   }
   

2. 특별한 의도를 설명할 때
   • 왜 이렇게 코드를 작성했는지 알려줍니다.

   // 퍼포먼스 향상을 위해 배열을 직접 순회함
   for (let i = 0; i < arr.length; i++) {
     // ...
   }
   

3. 함수의 매개변수와 반환값
   • JSDoc 같은 도구를 사용하면 함수 문서를 자동으로 생성할 수 있습니다.

   /**
    * 두 숫자를 곱합니다.
    *
    * @param {number} a 첫 번째 숫자
    * @param {number} b 두 번째 숫자
    * @return {number} 곱셈 결과
    */
   function multiply(a, b) {
     return a * b;
   }
   

---

6. 리팩토링으로 주석 줄이기 🔧

Before:

// 위스키를 더해줍니다
for (let i = 0; i < 10; i++) {
  let drop = getWhiskey();
  smell(drop);
  add(drop, glass);
}

// 주스를 더해줍니다
for (let i = 0; i < 3; i++) {
  let tomato = getTomato();
  let juice = press(tomato);
  add(juice, glass);
}

After:

addWhiskey(glass);
addJuice(glass);

function addWhiskey(container) {
  for (let i = 0; i < 10; i++) {
    let drop = getWhiskey();
    add(drop, container);
  }
}

function addJuice(container) {
  for (let i = 0; i < 3; i++) {
    let tomato = getTomato();
    let juice = press(tomato);
    add(juice, container);
  }
}

• 함수 이름 자체가 무슨 일을 하는지 설명합니다.
• 함수가 "하나의 역할"만 하도록 작성하면 주석 없이도 명확해집니다.

---

7. 주석 작성 요약 🖋️

• 좋은 주석
  • 코드를 작성한 의도, 복잡한 로직, 함수 용례를 설명
  • 아키텍처, 특별한 해결 방식을 기록
• 나쁜 주석
  • 코드로 알 수 있는 내용을 반복
  • 코드가 불명확할 때 어설프게 덮는 용도로 사용

---

실전 연습 문제 💡

1. 아래 코드를 더 좋은 방식으로 리팩토링해보세요. 주석 없이도 이해할 수 있도록 만들어보세요.

// 이 함수는 숫자가 소수인지 확인합니다
function isPrime(n) {
  for (let i = 2; i < n; i++) {
    if (n % i === 0) return false; // 나눠떨어지면 소수가 아님
  }
  return true; // 소수임
}

1. 주석을 잘 활용한 실전 사례를 찾아서 공유하고, 어떤 점이 좋은지 분석해보세요.
2. 여러분의 코드에서 가장 최근에 작성한 주석을 점검해보고, "이 주석이 정말 필요한가?"를 고민해보세요.