[클린코드] 4장 주석

책에서 기억하고 싶은 내용을 써보세요.

오래된 주석은 거짓말을 한다.
때문에 주석에 의존하기보다 코드의 표현력을 높이는데 에너지를 쏟아야 한다.

• 주석은 나쁜 코드를 보완하지 못한다.
  • 난장판이 된 코드는 주석을 달기보다 코드를 정리하는데 힘쓰자.
• 코드로 의도를 표현하라!
  • 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.
• 좋은 주석
  • 법적인 주석
  • 기본적인 정보를 제공하는 주석
  • 의도를 설명하는 주석
  • 의미를 명료하게 밝히는 주석
  • 결과를 경고하는 주석
  • TODO 주석
  • 중요성을 강조하는 주석
• 나쁜 주석
  • 쓸데없는 이야기를 하는 주석(의미불명, 반복, 당연한 이야기)
  • 잘못된 복사, 붙여넣기로 인한 잘못된 주석
  • 함수나 변수로 표현이 가능한 주석
  • 위치를 표시하는 주석
  • 주석으로 처리한 코드 -> 소스 코드 관리 시스템을 사용하자.
  • 쓸데없는 정보 나열
  • 비공개 코드에서 Javadocs

[리팩토링 예제]
지정한 수까지 소수를 구하는 알고리즘. 에리스토테네스의 체

1. 통으로 하나의 클래스로 구성되어있는 것을 클래스 안에 여러 메소드로 분리.
2. 주석으로 설명된 부분을 변수명, 메소드명으로 대체.
3. 어떤 알고리즘인지 알려주는 주석은 남겨놓아 이해하기 쉽게 함.
4. 루프한계 값을 지정수의 제곱근으로 설정한 이유를 남겨 놓음.
   • 변수명이나 코드 변경으로 이유를 설명하기 어려움

오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요.

다음 사람을 위해 주석을 잘 써놓는 것이 능사인 줄 알았다. 경험 상 너무 필요없이 지저분하기만 하다고 생각한 주석들은 있었지만 그 밖에도 훨씬 많은 주석들이 불필요하다는 것을 알게 되었다.

궁금한 내용이 있거나, 잘 이해되지 않는 내용이 있다면 적어보세요.

영어권 국가가 아니기 때문에 영어로 된 코드가 한 눈에 들어오지 않는다. 그래서 때로는 메소드명이나 변수명보다 한글로 써놓은 주석들이 눈에 잘 들어오기도 한다. 또한, 코드를 깨끗하게 쓰는 능력이 부족하여 주석이 없는 것이 오히려 힘든 경우들도 존재한다. 주석을 어느 정도로 쓰는 것이 적당한 것인지에 대한 고민은 더 필요한 것 같다.