북클럽 클린코드 4장. 주석

[!NOTE]
나쁜 코드에 주석을 달지 마라. 새로 짜라.

잘 달린 주석은 그 어떤 정보보다 유용하다.
경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다.
오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다.

주석은 기껏해야 필요악이다.
주석은 언제나 실패를 의미한다.
주석은 반겨 맞을 손님이 아니다.

고민하자

주석이 필요한 상황에 처하면 곰곰이 생각하기 바란다.
코드로 의도를 표현할 방법은 없을까?
코드로 의도를 표현할 때마다 스스로를 칭찬해준다.
주석을 달 때마다 자신에게 표현력이 없다는 사실을 푸념해야 마땅하다.

왜 주석 욕해?

• 주석은 거짓말을 한다.
• 너무 자주 한다.
• 유지보수가 너무나도 힘들다.
• 코드의 변화를 주석이 따라갈 수가 없다.
• 부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다.
• 진실은 한곳에만 존재한다. 바로 코드다.
• 코드만이 자기가 하는 일을 진실되게 말한다.
• 코드만이 정확한 정보를 제공하는 유일한 출처다.

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

• 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
  • 사이드이펙트가 있거나
  • 코드가 이해가 안되게 복잡하거나
• 원인을 해결해야 된다.

코드로 의도를 표현하라

• 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.
• 조건 요소들을 조건문에 고대로 박지 말고
• 의미를 담아서 함수 안에 넣어라

좋은 주석

• 좋은 주석도 있다.
• 글자 값을 한다고 생각하는 주석 사례!
  • 법적인 주석
  • 정보를 제공하는 주석 : 길지 않게 기본적인 정보
  • 의도를 설명하는 주석 : 결정에 깔린 의도까지 설명
  • 의미를 명료하게 밝히는 주석 : 모호한 인수나 반환값의 의미
    • 코드를 바꾸는게 더 좋지만 외부 라이브러리 등 코드 수정이 어려운 경우
  • 결과를 경고하는 주석
    • 소요시간이 오래 걸리는 경우
    • Thread-Safe 하지 않은 경우 등
  • TODO 주석
    • 예시
      • 함수를 구현하지 않은 이유와 미래의 모습을 작성
      • 필요하다 여기지만 당장 구현하기 어려운 업무
      • 더이상 필요 없는 기능을 삭제하라는 알림
      • 누군가에게 문제를 봐달라는 요청
      • 더 좋은 이름을 떠올려달라는 부탁
      • 앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의
    • 주기적으로 정리할 필요는 있음
  • 중요성을 강조하는 주석
    • 누가 슥 지워버릴 수 있는 코드. 이거 뭐지 왜있지? 싶은 경우
  • 공개 API에서 Javadocs
    • 공개 API는 설명이 있어야만 한다!

나쁜 주석

• 대부분의 주석
• 주석 사례
  • 주절거리는 주석. 정확한 정보 X. 쓰다만 주석.
  • 같은 이야기를 중복하는 주석
  • 오해할 여지가 있는 주석 : 명확하게 말해야 된다.
  • 의무적으로 다는 주석 : 필요한데만 달자.
  • 이력을 기록하는 주석 : 변경 이력 완전 쓸데없다. 제거하라.
  • 있으나 마나 한 주석 : 너무나 당연한 사실
    • 개발자가 주석을 무시하는 습관에 빠진다.
  • 함수나 변수로 표현할 수 있다면 주석을 달지 마라
  • 위치를 표시하는 주석
    • 이 아래로 특정 함수들이 모여있어
    • 아주 드물게 사용하는 편이 좋다.
  • 닫는 괄호에 다는 주석
    • 필요하면 IDE의 플러그인 있으니 써라
    • 그냥 함수를 짧게 써라
  • 공로를 돌리거나 저자를 표시하는 주석
    • 뭐하는 거야? 소스컨트롤이 알아서 해준다.
    • 코드에는 코드 관련 내용만 넣어라
  • 주석으로 처리한 코드
    • 코드 바꾸면 그냥 다 지워라 기존 코드 남겨두지 말고
    • 이유가 있어서 남겨뒀겠찌? 이유는 대부분 없고 아무도 안지운다.
  • HTML 주석
  • 전역 정보 : 설명 범위가 너무 넓어서는 안된다. 해당 요소에 대한 설명이어야 함.
  • 너무 많은 정보
  • 모호한 관계 : 예시는 이유 없이 결과에 대한 설명만 있는 경우
  • 비공개 코드에서 Javadocs : 공개 하지 않을거면 쓸모가 없다.
  • 예제
    • 주석은 군데군데 박히는거보다 모아놓는게 낫다.
    • 알고리즘 설명은 필요하다고 생각한다.