[4장] 주석

---

주석은 나쁜 코드를 보완하지 못한다.

• "이런 주석을 달아야겠다!" → "코드를 정리해야겠다!"
• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가
  복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.

---

코드로 의도를 표현하라!

• 확실히 코드만으로 의도를 설명하게 어려운 경우가 존재하지만,
  그것이 코드가 훌륭한 수단이 아니라는 의미는❌

if((employee.flags & HOURLY_FLAG) &&
   (employee.age > 65))

if(employee.isEligibleForFullBenefits())

---

좋은 주석

• 법적인 주석

  • 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣는 경우
  • EX) 각 소스 파일 첫 머리에 주석으로 들어가는 저작권 정보, 소유권 정보

• 정보를 제공하는 주석

  • 때로는 기본적인 정보를 주석으로 제공하면 편리하다.
  • 그럼에도 불구하고, 가능하다면, 함수 이름에 정보를 담는 것이 좋다.

• 의도를 설명하는 주석

  • 때로는 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다.

• 의미를 명료하게 밝히는 주석

  • ⚠ 필요한, 동시에 위험한 주석
  • 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면, 의미를 명료하게 밝히는 주석이 유용하다.
  • 일반적으로는, 가능하다면, 인수나 반환값 자체를 명확하게 만드는 것이 더 좋다.

• 결과를 경고하는 주석

  • EX) 특정 테스트 케이스르 꺼야하는 이유

• TODO 주석

  • 앞으로 해야할 일
  • EX) 함수를 구현하지 않은 이유와 미래 모습, 당장 구현하기 어려운 업무, 기능 삭제 알림, 코드 개선 알림...

• 중요성을 강조하는 주석

• 공개 API에서 Javadocs

  • ⚠ 잘못된 정보 전달 가능성 ↑
  • 공개 API를 구현한다면 반드시 훌륭한 Javadocs를 작성.

---

나쁜 주석

• 주절거리는 주석

  • 특별한 이유 없는 주석은 ❌
  • 달려면 제대로 달아라!

• 같은 이야기를 중복하는 주석

  • 코드보다 읽는 시간이 오래 걸리는 주석은 ❌

• 오해할 여지가 있는 주석

• 의무적으로 다는 주석

  • 억지로 다는 주석은 잘못된 정보를 제공할 여지만 만든다.

• 이력을 기록하는 주석

  • 이전에는 변경 이력을 기록하고 관리하는 관례가 바람직했다.
    코드 관리 시스템이 없었으니까.

• 있으나 마나 한 주석

  • 당연한 사실을 언급하는 주석은 ❌

• 무서운 잡음

  • 문서를 제공해야 한다는 잘못된 욕심이 붙여넣기 유혹과 잘못된 정보에 빠지게 만든다.

• 닫는 괄호에 다는 주석

  • 닫는 괄호에 주석 → 캡슐화 개선 or 함수 줄이기

• 공로를 돌리거나 저자를 표시하는 주석

  • 소스 관리 시스템이 기억하기 때문에, 이는 코드를 오염시키는 것이다.

• 주석으로 처리한 코드

  • 역시 코드 관리 시스템이 기억하기 때문에, 주저 없이 삭제할 것!

• HTML 주석

• 전역 정보

  • 근처에 있는 코드만 기술할 것!

• 너무 많은 정보

• 모호한 관계

  • 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.

• 함수 헤더

  • 짧은 함수는 긴 설명이 필요 없다.
  • 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 훨씬 좋다.

• 비공계 코드에서 Javadocs

  • 공계하지 않을 코드에서 Javadocs는 쓸모가 없다.

---

인상 깊었던...

하지만 나라면 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로, 그래서 애초에 주석이 필요 없는 방향으로 에너지를 쏟겠다.

진실은 한곳에만 존재한다. 바로 코드다. 코드만이 자기가 하는 일을 진실되게 말한다.

하지만 명심하기 바란다. 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라는 사실을!

주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다.

---