4장 주석

있으나 마나 한 주석을 달려는 유혹에서 벗어나 코드를 정리하라.
더 낫고, 행복한 프로그래머가 되는 지름길이다.

 

함수나 변수로 표현할 수 있다면 주석을 달지 마라

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

 

코드로 의도를 표현하라!

// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) &&
	(employee.age > 65))

위 코드보단

if (employee.isEligibleForFullBenefits())

 

좋은 주석

법적인 주석
정보를 제공하는 주석
의도를 설명하는 주석
의미를 명료하게 밝히는 주석
결과를 경고하는 주석
TODO 주석
중요성을 강조하는 주석

하지만 코드로 설명할 수 있다면 그것이 베스트

 

위치를 표시하는 주석

반드시 필요할 때만, 아주 드물게 사용하는 편이 좋다. 배너를 남용하면 독자가 흔한 잡음으로 여겨 무시한다.

개인적으로는 이렇게 구분되어 있으면 읽기가 편하던데... (원하는 부분을 찾아가기 편함)
그렇지만 잘 짜여 있다면 이런 것도 필요 없으려나..

 

예제

// PrimeGenerator.java

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

첫 번째 주석이 중복이라고 주장하기 쉽다. 설명이 generatePrimes 함수 자체와 아주 흡사하기 때문이다. 그래도 나는 주석이 있어 알고리즘을 이해하기 쉬워진다고 생각한다. 그래서 남겨 두는 편을 택했다.

두 번째 주석은 거의 확실히 필요하다. 루프 한계값으로 제곱근을 사용한 이유를 설명한다. 나로서는 변수 이름을 바꾸거나 코드 구조를 조정해 이유를 명확하게 설명할 방법을 찾지 못했다. 다른 한편으로 제곱근의 사용은 나만의 생각일지도 모르겠다. 제곱근까지만 루프를 돌면 정말로 시간을 절약할까? 제곱근 계산에 오히려 시간이 더 들지 않을까?
  숙고할 가치가 있는 문제다. 늙은 C/어셈블리 프로그래머인 내게는 제곱근이 만족스러운 해법이지만 남들이 이를 이해하려 시간과 노력을 투자할 가치가 있는지는 잘 모르겠다.

새로운 시각(?)으로 마무리를 해주셔서 좋았다. 이 장에서 느낀 건 역시 주석은 '코드를' 설명하는 게 아니라 코드의 '의도와 맥락'을 설명해야 한다. 물론 그마저도 필요 없다면 베스트....