DAY 9

🔖 오늘 읽은 범위 : 4장 주석 (75~94p)

---

🤓 책에서 기억하고 싶은 내용

나쁜 주석

주절거리는 주석

• 이유없이 의무감이나 업무 표준때문에 마지못해 주석을 단다면 시간 낭비 주석을 달기로 결정했다면 최고의 주석을 달아라

  public void loadProperties() {
      try {
          String propertiesPath = propertiesLocation + "/" + PROPERTIES_FILE;
          FileInputStream propertiesStream = new FileInputStream(propertiesPath);
          loadedProperties.load(propertiesStream);
      } catch (IOException e) {
          // 속성 파일이 없다면 기본값을 모두 메모리로 읽어 들였다는 의미다. }
      }
  }

  이해가 안 되어 다른 모듈까지 뒤져야 하는 주석은 낭비
  

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

• 코드의 내용을 반복하거나 덜 언급하는 주석은 피하라
• 엔진 후드를 열어볼 필요가 없다며 고객에게 아양 떠는 중고차 판매원이 되지말자

  // this.closed가 true일 때 반환되는 유틸리티 메서드다.
  // 타임아웃에 도달하면 예외를 던진다.
  public synchronized void waitForClose(final long timeoutMillis) throws Exception {
      if (!closed) {
          wait(timeoutMillis);
          if (!closed)
              throw new Exception("MockResponseSender could not be closed");
      }
  }

  추가 정보를 제공 못하는 의미없는 주석
  

오해할 여지가 있는 주석

• 위의 타임아웃 주석에 대해 this.closed가 변하는 순간에 메서드가 반환된다고 오해할 여지가 있음

의무적으로 다는 주석

• Javadocs 같은 주석을 의무적으로 달 필요는 없다
• 변경이력은 git으로 관리해야지 주석으로 관리하지말라

있으나 마나 한 주석

• 너무나 당연한 사실을 언급하는 주석은 ❌ → 개발자가 주석을 무시하는 습관에 빠지게 한다

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

// 전역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))

미리 주석을 쓰고 개발했을수도있겠지만.. 다개발했으면 정리, 아래와 같이 변경

ArrayList moduleDependees = smodule.getDependSubsystems(); 
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))

위치를 표시하는 주석

• 소스파일에서 특정 위치를 표시하려 주석 사용

  // Actions //////////////////////////////////

  위와 같은 배너의 기능으로 주의를 환기하는 주석을 쓸 수 있지만 꼭 필요할 때만 쓴다
  

닫는 괄호에 다는 주석

• 함수가 장황할 때 닫는 괄호에 주석 다는 경우가 있지만 그럴바에는 함수를 줄이자

  public class wc {
      public static void main(String[] args) {
          BufferedReader in = new BufferedReader(new InputStreamReader(System.in));
          String line;
          int lineCount = 0;
          int charCount = 0;
          int wordCount = 0;
          try {
              while ((line = in .readLine()) != null) {
                  lineCount++;
                  charCount += line.length();
                  String words[] = line.split("\\W");
                  wordCount += words.length;
              } //while
              System.out.println("wordCount = " + wordCount);
              System.out.println("lineCount = " + lineCount);
              System.out.println("charCount = " + charCount);
          } //try
          catch (IOException e) {
              System.err.println("Error:" + e.getMessage());
          } //catch } //main
      }

  1960년대까지는 주석으로 관리했지만 이제는 소스 관리 시스템이 있으므로 과감히 지워라
  

HTML 주석

• 주석에 html 태그 삽임은 프로그래머가 아니라 도구가 해야함

  /**
   * 적합성 테스트를 수행하기 위한 과업
   * 이 과업은 적합성 테스트를 수행해 결과를 출력한다.
   * <p/>
   * <pre>
   * 용법:
   * &lt;taskdef name=&quot;execute-fitnesse-tests&quot;
   * classname=&quot;fitnesse.ant.ExecuteFitnesseTestsTask&quot;
   * classpathref=&quot;classpath&quot; /&gt;
   * 또는
   * &lt;taskdef classpathref=&quot;classpath&quot;
   * resource=&quot;tasks.properties&quot; /&gt;
   * <p/>
   * &lt;execute-fitnesse-tests
   * suitepage=&quot;FitNesse.SuiteAcceptanceTests&quot;
   * fitnesseport=&quot;8082&quot;
   * resultsdir=&quot;${results.dir}&quot;
   * resultshtmlpage=&quot;fit-results.html&quot;
   * classpathref=&quot;classpath&quot; /&gt;
   * </pre> */

전역 정보

• 주석을 굳이 달아야 한다면 근처에 있는 코드 관련 정보만 기술하자
• 시스템의 전반적인 정보를 기술하지 마라

너무 많은 정보

• 흥미로운 역사나 관련없는 정보를 늘어놓지 마라

/*
RFC 2045 - Multipurpose Internet Mail Extensions (MIME)
1부: 인터넷 메시지 본체 형식
6.8절. Base64 내용 전송 인코딩(Content-Transfer-Encoding)
인코딩 과정은 입력 비트 중 24비트 그룹을 인코딩된 4글자로 구성된
출력 문자열로 표현한다. 왼쪽에서 오른쪽으로 진행해가며, 3개를 묶어 8비트 입력
그룹을 형성한다. 이렇게 만들어진 24비트는 4개를 묶어 6비트 그룹으로 취급하며,
각각은 base64 알파벳에서 단일 자릿수로 해석된다.
base64 인코딩으로 비트 스트림을 인코딩할 때, 비트 스트림은
MSB(Most Significant Bit) 우선으로 정렬되어 있다고 가정한다. 따라서, 스트림에서 첫 번째 비트는 첫 8비트 바이트에서 최상위 비트가 되며, 여덟번째 비트는 첫 8비트 바이트에서 최하위 비트가 된다.
*/

모호한 관계

• 주석과 코드의 관계가 명확해야함

  /*
  RFC 2045 - Multipurpose Internet Mail Extensions (MIME)
  1부: 인터넷 메시지 본체 형식
  6.8절. Base64 내용 전송 인코딩(Content-Transfer-Encoding)
  인코딩 과정은 입력 비트 중 24비트 그룹을 인코딩된 4글자로 구성된
  출력 문자열로 표현한다. 왼쪽에서 오른쪽으로 진행해가며, 3개를 묶어 8비트 입력
  그룹을 형성한다. 이렇게 만들어진 24비트는 4개를 묶어 6비트 그룹으로 취급하며,
  각각은 base64 알파벳에서 단일 자릿수로 해석된다.
  base64 인코딩으로 비트 스트림을 인코딩할 때, 비트 스트림은
  MSB(Most Significant Bit) 우선으로 정렬되어 있다고 가정한다. 따라서, 스트림에서 첫 번째 비트는 첫 8비트 바이트에서 최상위 비트가 되며, 여덟번째 비트는 첫 8비트 바이트에서 최하위 비트가 된다.
  */

  주석의 필터바이트가 뭘 얘기하는지, 200을 왜 더하는지 알 수 가없다
  

함수 헤더

• 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다

비공개 코드에서 Javadocs

• 공개하지 않을 코드라면 Javadocs 쓰지 말자

예제

/**
 * 이 클래스는 사용자가 지정한 최대 값까지 소수를 생성한다. 사용된 알고리즘은
 * 에라스토테네스의 체다.
 * <p>
 * 에라스토테네스: 기원전 276년에 리비아 키레네에서 출생, 기원전 194년에 사망
 * 지구 둘레를 최초로 계산한 사람이자 달력에 윤년을 도입한 사람.
 * 알렉산드리아 도서관장을 역임.
 * <p>
 * 알고리즘은 상당히 단순하다. 2에서 시작하는 정수 배열을 대상으로
 * 2의 배수를 모두 제거한다. 다음으로 남은 정수를 찾아 이 정수의 배수를 모두 지운다.
 * 최대 값의 제곱근이 될 때까지 이를 반복한다. *
 * @author Alphonse
 * @version 13 Feb 2002 atp */
import java.util.*;
public class GeneratePrimes {
    /**
     * @param maxValue는 소수를 찾아낼 최대 값
     */
    public static int[] generatePrimes(int maxValue) {
        if (maxValue >= 2) // 유일하게 유효한 경우 
        {
            // 선언
            int s = maxValue + 1; // 배열 크기 
            boolean[] f = new boolean[s];
            int i;
            // 배열을 참으로 초기화
            for (i = 0; i < s; i++)
                f[i] = true;
            // 소수가 아닌 알려진 숫자를 제거 
            f[0] = f[1] = false;
            // 체
            int j;
            for (i = 2; i < Math.sqrt(s) + 1; i++) {
                if (f[i]) // i가 남아 있는 숫자라면 이 숫자의 배수를 구한다. {
                    for (j = 2 * i; j < s; j += i)
                        f[j] = false; // 배수는 소수가 아니다.
            }
        }
        // 소수 개수는?
        int count = 0;
        for (i = 0; i < s; i++) {
            if (f[i])
                count++; // 카운트 증가
        }
        int[] primes = new int[count];
        // 소수를 결과 배열로 이동한다.
        for (i = 0, j = 0; i < s; i++) {
            if (f[i]) // 소수일 경우에
                primes[j++] = i;
        }
        return primes; // 소수를 반환한다. }
        else // maxValue < 2
            return new int[0]; // 입력이 잘못되면 비어 있는 배열을 반환한다.
    }
}

아래코드로 변경

/**
 * 이 클래스는 사용자가 지정한 최대 값까지 소수를 구한다. * 알고리즘은 에라스토테네스의 체다.
 * 2에서 시작하는 정수 배열을 대상으로 작업한다.
 * 처음으로 남아 있는 정수를 찾아 배수를 모두 제거한다. * 배열에 더 이상 배수가 없을 때까지 반복한다.
 */
public class PrimeGenerator {
    private static boolean[] crossedOut;
    private static int[] result;
    public static int[] generatePrimes(int maxValue) {
        if (maxValue < 2) return new int[0];
        else {
            uncrossIntegersUpTo(maxValue);
            crossOutMultiples();
            putUncrossedIntegersIntoResult();
            return result;
        }
    }

    private static void uncrossIntegersUpTo(int maxValue) {
        crossedOut = new boolean[maxValue + 1];
        for (int i = 2; i < crossedOut.length; i++)
            crossedOut[i] = false;
    }
    private static void crossOutMultiples() {
        int limit = determineIterationLimit();
        for (int i = 2; i <= limit; i++)
            if (notCrossed(i)) crossOutMultiplesOf(i);
    }
    private static int determineIterationLimit() {
        // 배열에 있는 모든 배수는 배열 크기의 제곱근보다 작은 소수의 인수다. 
        // 따라서 이 제곱근보다 더 큰 숫자의 배수는 제거할 필요가 없다. 
        double iterationLimit = Math.sqrt(crossedOut.length);
        return (int) iterationLimit;
    }
    private static void crossOutMultiplesOf(int i) {
        for (int multiple = 2 * i; multiple < crossedOut.length; multiple += i; crossedOut[multiple] = true;
        }
        private static boolean notCrossed(int i) {
            return crossedOut[i] == false;
        }
        private static void putUncrossedIntegersIntoResult() {
            result = new int[numberOfUncrossedIntegers()];
            for (int j = 0, i = 2; i < crossedOut.length; i++)
                if (notCrossed(i)) result[j++] = i;
        }
        private static int numberOfUncrossedIntegers() {
            int count = 0;
            for (int i = 2; i < crossedOut.length; i++)
                if (notCrossed(i)) count++;
            return count;
        }
    }

첫 번째 주석: generatePrimse 라는 함수 이름으로 설명이 되긴 하지만 알고리즘의 쉬운 이해를 위해 남겨둠

두 번째 주석: 루프 한계값으로 제곱근을 사용한 이유를 설명 (코드로 설명 한계 있음)

🤔 떠오르는 생각

• 나는 코드가 아니여도 항상 까마귀처럼 남겨두거나 수집하는 버릇이 있었는데, 이제 모든 주석을 과감히 정리하고 지워 버려야겠다

🔎 질문

📝 소감 3줄 요약

• 엔진 후드를 열어볼 필요가 없다며 고객에게 아양 떠는 중고차 판매원이 되지말자
• 주석을 굳이 달아야 한다면 근처에 있는 코드 관련 정보만 기술하자
• 1960년대까지는 주석으로 히스토리 관리했지만 이제는 소스 관리 시스템이 있으므로 과감히 지워라