클린 코드

주석 🙌

⚠️ 주석은 나쁜 코드를 보완하지 못한다.
⚠️ 또한 주석은 방치된다. 😵

// 중복된 상품 선택을 막기 위해 진행중인 A 타입의 상품이 존재하는지 확인한다. 
if (product && product.state === 'ONGOING' && product.type === 'A') { }

요구 사항이 변경되어 타입과 상관없이 중복 상품 선택을 할 수 없게 한다면?.. 🤔

// 중복된 상품 선택을 막기 위해 진행중인 A 타입의 상품이 존재하는지 확인한다. 
if (product && product.state === 'ONGOING') { }

주석은 그대로 방치된다면 나중에 해당 코드를 보고 product 자체가 A 타입이구나.. 라는 오해를 만들 수 있고
이는 오류로 이어질 수 있다.

불필요한 주석은 쓰지 말고 의미 있는 이름을 짓도록 하자

// 의미있는 이름을 짓자.
if (isDuplicatedProduct()) { }

클린코드에서 설명한 좋은 주석이라고 말하는 주석은 다음과 같다.

정보를 제공하는 주석
의도를 설명하는 주석
의미를 명료하게 밝히는 주석
결과를 경고하는 주석

하지만 책에서는 해당 주석들도 더 나은 방법이 없는지 고민하고 정확히 달도록 주의하라고 한다.

🟢 TODO 주석 : 앞으로 해야 할 일이나 지금은 해결하지 않지만 나중에 해야할 일을 미리 적어둔다.

앞으로의 할 일을 TODO 주석으로 남겨두면 편하다.

해당 주석은 IDE에서 TODO 주석 전부를 찾아 보여주는 기능을 제공하고 있고 하이라이팅이 된다.

물론.. TODO로 떡칠한 코드는 바람직하지 않고 주기적으로 기능을 개발하여 TODO를 지우도록 노력하자.

✅ @Deprecated

deprecated 뜻은 중요도가 떨어져 더 이상 사용되지 않고 앞으로는 사라지게 될 을 의미하는 형용사이다.

(chiefly of a software feature) be usable but regarded as obsolete and best avoided, typically because it has been superseded.

deprecated는 뜻과 마찬가지로 더 이상 사용하지 않거나, 다른 함수가 해당 기능을 대신하게 되는 경우 사용하게 된다.

/**
   * @deprecated 다른 함수에서 조회하도록 변경하였습니다. {@link #getCourseCountByCourseId}
   */
  async getCourseCount(courseId) {
  }

~~getCourseCount~~

해당 기능을 사용하면 해당 함수에 취소선이 그어진다. 😉

✅ JavaDoc

deprecated 이외에 다양한 태그가 존재한다.

나쁜 코드에 주석을 달지 말라. 새로 짜라
브라이언 W. 커니핸, P.J. 플라우거