[Study][CleanCode - 1] 4. 주석

📋 목차.

4. 주석
    .좋은 주석
    .나쁜 주석

---

✔️ 내용.

 

4. 주석

 

 주석이 필요한 상황마다 코드로 표현할 방법이 정말로 없는지 다시 한번 생각해본다.
주석은 오래도리수록 코드에서 멀어진다. 주석을 유지보수 하기란 현실적으로 어렵기 때문이다.
부정확한 주석은 없는 주석만 못하다. 코드만이 자기가 하는 일을 진실되게 말한다. 
그러므로 주석을 가능한 줄이도록 꾸준히 노력한다.

 

---

 

.좋은 주석

 

어떤 주석은 필요하거나 유익하다. 하지만 정말로 좋은 주석은, 주석을 달지 않는 방법이라는 것을 명심한다.

 

- 법적인 주석

 

때로는 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣으라고 명시한다.

 

// Copyright (C) 2003,2004,2005 by Object Mentor, Inc, All rights reserved.
// GNU General Public License 버전 2이상을 따르는 조건으로 배포한다.

 

- TODO 주석

 

 때로는 '앞으로 할 일'을 주석으로 남겨두면 편하다.

필요하다 여기지만 당장 구현에 힘든 업무일 경우 TODO 주석으로 기술한다.

단, 주기적으로 TODO 주석을 점검해 괜찮은 주석은 없애도록 해야한다.

 

- 복잡한 알고리즘에 있어 알고리즘을 이해하기 쉽게 하는 주석

 

 알고리즘을 이해하기 쉬워짐에 있어 도움이 될 경우 남겨두는 것을 선호하는 편이다. (필자 동감)
제곱근(Math.sqrt)을 사용한 이유에 대해 설명한다. 제곱근이 정말 좋은 방법인가에대해 설명하고 숙고할 가치가 문제이기 떄문에 남겨둔다. (필자 동감)

 

/**
 * 이 클래스는 사용자가 지정한 최대 값까지 소수를 구한다.
 * 알고리즘은 에라스토테네스의 체다.
 * 2에서 시작하는 정수 배열을 대상으로 작업한다.
 * 처음으로 남아 있는 정수를 찾아 배수를 모두 제거한다.
 * 배열에 더 이상 배수가 없을 때까지 반복한다.
 */
public class PrimeGenerator{
  
  private static int intdetermineIterationLimit(){
    // 배열에 있는 모든 배수는 배열 크기의 제곱근보다 작은 소수의 인수다.
    // 따라서 이 제곱근보다 더 큰 숫자의 배수는 제거할 필요가 없다.
    double iterationLimit = Math.sqrt(crossedOut.length);
    return (int) iterationLimit;
  }
}

 

---

 

.나쁜 주석

 

대부분의 주석에 대해 부정적이기 때문에 간단하게 목록만 나열 하도록 한다.

 

- 주절거리는 주석

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

- 오해할 여지가 있는 주석

- 의무적으로 다는 주석

- 이력을 기록하는 주석

- 있으나 마나한 주석

 

- 등등..

---

 

📝 느낀점.

- 대체적으로 주석을 사용하지 말라는 내용이 핵심으로 이해하고 대부분의 내용을 생략 하였다.
- 필요한 주석 몇개에 공감가는 부분이 있어서 기술하게 되었다.