[클린코드] 4장 주석 (with Typescript)

핵심 요약

• 주석이 필요하다는 것은 코드가 명확하게 짜여있지 않다는 뜻이다.
• ⇒ 주석을 잘 작성하는 것보다 코드의 표현력을 개선해서 주석을 제거하려고 노력하는 것이 바람직하다.
• 주석으로 나타내려는 설명을 함수나 변수로 표현하라.
• 코드가 이미 표현하고 있는 정보를 주석으로 중복 설명하지 마라.
• 소스 코드 관리 시스템이 줄 수 있는 정보를 주석으로 표현하지 마라.
• 주석 근처에 있는 코드에 대한 정보만 기술하라.
  • 전역적인 정보나 다른 위치에 있는 코드에 의존하는 정보는 기술하지 않는다.

---

4장 주석

주석을 사용하는 이유는 코드로 의도를 표현하지 못했기 때문이다.

주석은 순수하게 선하지 못하다. 프로그래머들이 주석을 유지하고 보수하기란 현실적으로 불가능하기 때문이다.

따라서 주석은,

1. 거짓말을 자주 한다.
2. 오래될수록 코드에서 멀어지고 분리된다.

코드를 깔끔하게 유지하고 표현력을 강화하여 애초에 주석이 필요 없는 방향으로 에너지를 쏟는 것이 바람직하다.

 

코드로 의도를 표현하라

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

// 🟢 Good
if(employee.isEligibleForFullBenefits())

코드로 충분히 의도를 표현할 수 있다.

위 예시에서는 주석으로 달려는 설명을 함수로 만들어 표현하였다.

 

좋은 주석

 

법적인 주석

표준에 맞춰 작성된 저작권, 소유권, 라이선스, 참조한 외부 문서 정보 등

 

기본적인 정보를 제공하는 주석

예시 1)

// 테스트 중인 Responder 인스턴스를 반환한다.
function getResponderInstance(): Responder {...}

위와 같이 메서드가 반환할 값을 구체적으로 설명하는 주석은 편리하다.

하지만 가능하다면 주석의 정보를 함수명으로 표현하는 것이 더 좋다.

function getResponderBeingTested(): Responder {...}

예시 2)

// yyyy-MM-dd hh:mm:ss
const timePattern = /([0-2][0-9]{3})-([0-1][0-9])-([0-3][0-9]) ([0-5][0-9]):([0-5][0-9]):([0-5][0-9])(([\-\+]([0-1][0-9])\:00))?/;

주석으로 정규표현식이 어떤 포맷을 나타내는지 잘 설명해 준다.

 

의도를 설명하는 주석

주석은 결정에 깔린 저자의 의도를 설명할 수 있다.

이런 의도는 주로 코드로 표현하기 어렵다. 이런 정보에 한해서 주석은 유용하게 쓰일 수 있다.

 

의미를 명료하게 밝히는 주석

모호한 인수나 반환값의 의미를 읽기 좋게 표현하면 이해하기 쉬워진다.

인수나 반환값 자체를 명확하게 만들기 힘든 코드(ex. 표준 라이브러리 또는 변경할 수 없는 코드)라면 주석이 유용하다.

members.sort((a, b) => a.age - b.age) // 나이를 기준으로 오름차순 정렬

⚠️ 주의할 점: 주석이 올바른지 검증할 수 없다.

잘못된 주석을 달아놓을 위험이 높다. 따라서 주석보다 더 나은 방법이 없는지 고민하고 정확히 달도록 각별히 주의해야 한다.

 

결과를 경고하는 주석

다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용할 수 있다.

// DOM을 참조하므로 Server Side에서 호출하지 마십시오.
function changeBackgroundColor(color: string) {
    document.body.style.color = color
}

 

TODO 주석

다음과 같은 상황에 TODO 주석을 남기면 유용하다.

• 앞으로 할 일
• 당장 구현하기 어려운 것
• 검토가 필요한 코드
• 기획이 추가됨에 따라 추가 구현해야 할 코드

대다수 IDE에서는 TODO 주석을 특별한 색상으로 표시해 주거나 모아서 볼 수 있는 기능을 제공하므로 쉽게 추적할 수 있다.

주기적으로 TODO 주석을 점검하고 완료된 것은 제거하는 것이 좋다.

내가 사용하고 있는 VSCode Extention: Todo Tree

 

중요성을 강조하는 주석

자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해 주석을 사용한다.

 

공개 API에서 JsDoc

공개 API를 구현 한다면 반드시 훌륭한 JsDoc을 작성한다.

JsDoc이 잘 작성되어 있다면 동적 타입 언어인 자바스크립트에서 타입에 대한 힌트를 제공할 수 있다.

파일에 //@ts-check 주석이 있다면 타입스크립트처럼 타입 체킹을 해준다.

이를 통해 자바스크립트를 사용하는 프로그래머가 api를 올바르게 사용하도록 강제할 수 있다.

// @ts-check
/**
 *  @param a {number}
 *  @param b {number}
 *  @returns {number}
 */
const add = (a, b) => a + b;

add("2", 3) //Error: 'string' 형식의 인수는 'number' 형식의 매개 변수에 할당될 수 없습니다.

다만, 여느 주석과 마찬가지로 잘못된 정보를 전달하지 않도록 주의해야 한다.

 

나쁜 주석

대다수 주석이 이 범주에 속한다.

• 허술한 코드를 변명하는 주석
• 미숙한 결정을 합리화하는 주석
• 주절거리는 독백에 불과한 주석

 

주절거리는 주석

• 특별한 이유 없이 의무감 또는 정해진 프로세스 때문에 다는 주석
• 주석을 이해할 수 없어 다른 모듈까지 뒤져야 하는 주석

독자와 제대로 소통하지 못하는 주석은 바이트만 낭비할 뿐이다.

주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달아야 한다.

 

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

코드 내용을 그대로 중복하여 설명하는 주석을 피한다.

자칫하면 코드보다 주석을 읽는 시간이 더 오래 걸린다.

• 주석이 코드보다 더 많은 정보를 제공하지 못한다.
• 코드를 정당화하는 주석도 아니고, 의도나 근거를 설명하지도 않는다.
• 코드보다 읽기 쉽지 않다.
• 코드보다 부정확해 독자가 함수를 대충 이해하고 넘어가게 만든다.

 

오해할 여지가 있는 주석

의도는 좋지만 엄밀하게 주석을 달지 못하는 경우가 있다.

// closed가 true일 때 반환되는 유틸리티 함수
// 타임아웃에 도달하면 에러를 발생한다.
const setTimer = (timeoutMillies: number) => new Promise((resolve) => setTimeout(resolve, timeoutMillies))
async function waitForClose(timeoutMillies: number) {
  if(!closed) {
    await setTimer(timeoutMillies)
    if (!closed) throw new Error('MockResponseSender could not be closed.')
  }
}

위 코드는 함수가 반환되는 시점에 대한 오해의 여지가 있다.

프로그래머는 주석의 살짝 잘못된 정보로 인해 다음과 같은 생각으로 함수를 호출할 수 있다.

🧑‍💻: ‘closed가 true로 변하는 순간에 함수가 반환되겠구나’

실제로는 closed가 true여야 함수는 반환된다. 그게 아니면 무조건 타임아웃을 기다렸다가 closed가 그래도 true가 아니면 에러를 발생한다.

주석에 대한 오해 때문에 프로그래머는 코드가 느린 이유를 찾느라 골머리를 앓을 수 있다.

 

의무적으로 다는 주석 / 있으나 마나 한 주석 / 무서운 잡음

모든 함수에 jsDoc를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석다.

// 🔴 Bad
/**
 * 
 * @param title CD 제목
 * @param author CD 저자
 * @param tracks CD 트랙 숫자
 * @param durationInMinutes CD 길이 (단위: 분) 
 */
function addCD(
  title: string,
  author: string,
  tracks: number,
  durationInMinutes: number
) {
  const cd: CD = {
    title,
    author,
    tracks,
    durationInMinutes,
  };
  cdList.push(cd);
}

위에서 사용된 주석은 아무 가치가 없으며, 오히려 프로그래머를 혼동시킬 수 있다.

너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석이기도 하다.

이러한 주석은,

• 코드를 복잡하게 만든다.
• 잘못된 정보를 제공할 여지를 만든다.
• 개발자가 주석을 무시하는 습관에 빠지게 만든다.
• 결국엔 코드가 바뀌면서 주석은 거짓말로 변한다.

의미 없는 JSDoc은 문서를 제공해야 한다는 잘못된 욕심으로 탄생한 잡음일 뿐이다.

 

소스 코드 관리 시스템의 역할을 하는 주석

1. 이력을 기록하는 주석
2. 공로를 돌리거나 저자를 표시하는 주석
3. /* 하영이가 추가함 */
4. 주석으로 처리한 코드결국 쓸모없는 코드가 점차 쌓여가게 된다.
5. 🧑‍💻: 이유가 있어서 남겨놓은 건가? 중요한 내용이라 지우면 안 되는 건가? 코드를 급박하게 변경했다는 사실을 알려주려는 건가?
6. 주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다.

오랫동안 코드에 방치된 이런 주석은 점차 부정확하고 쓸모없는 정보로 변한다.

소스 코드 관리 시스템이 우리를 대신해 코드를 기억해 준다. 잃어버릴 염려는 버리고 주석을 삭제하라.

 

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

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

// 🟢 Good
const moduleDependees = smodule.getDependSubsystems()
const ourSubSystem = subSysMod.getSubSystem()
if (moduleDependees.contains(ourSubSystem))

주석이 필요하지 않도록 코드를 개선하는 편이 더 좋다.

적절한 이름의 변수를 사용하여 주석을 코드로 나타내자

 

위치를 표시하는 주석

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

위와 같은 배너 아래 특정 기능을 모아놓으면 유용한 경우도 드물게 있다.

하지만 일반적으로 가독성만 낮추므로 제거하는 것이 좋다. (특히 뒷부분 슬래시로 이어지는 잡음)

너무 자주 사용하지 않는다면 배너는 눈에 띄며 주의를 환기한다.

• 반드시 필요할 때만 사용하라
• 아주 드물게 사용하라
• 배너를 남용하면 독자가 잡음으로 여겨 무시한다

 

닫는 괄호에 다는 주석

중첩이 심하고 장황한 함수라면 의미가 있을 수도 있지만,

이런 경우 함수를 더 작게 만들고 캡슐화하도록 개선하는 것이 낫다.

// 🔴 Bad
const main = () => {
    try {
        while(){
            ...
      } // while
    } // try
    catch(e) {
    ...
    } // catch
} // main

 

전역 정보

주석을 달아야 한다면 근처에 있는 코드만 기술하라

코드 일부에 주석을 달면서 시스템의 전역 정보나 다른 코드에 의존적인 정보를 기술하지 마라

// 🔴 Bad
/** 적합성 테스트가 동작하는 포트: 기본값은 8082 **/
function setFitnessPort(fitnessPort: number) {
    ...
}

setFitnessPort 함수는 기본값을 통제하지 않는다.

포트 기본값을 설정하는 코드가 변해도 해당 주석이 변하리라는 보장은 전혀 없다.

결국 잘못된 정보를 전달할 가능성이 매우 크다.

 

비공개 코드에서 JSDoc

공개 API는 JSDoc이 유용하지만, 외부에서 사용할 코드가 아니라면 쓸모가 없다.

유용하지도 않고 JSDoc의 작성 형식으로 인해 코드만 산만해진다.

 

예제

에라토스테네스의 체 알고리즘을 구현한 코드이다. 리팩토링 전과 후를 비교하며 클린코드가 주석을 어떻게 대체할 수 있는지 확인해 보자.

/* 4-7 generatePrimes.ts */
export default function generatePrimes(maxValue: number) {
  if (maxValue >= 2) {
    // 유일하게 유효한 경우
    // 선언
    const s = maxValue + 1; // 배열 크기
    const f: boolean[] = new Array(s).fill(true); // 배열을 true로 초기화

    // 소수가 아닌 알려진 숫자를 제거
    f[0] = false;
    f[1] = false

    //체
    for (let i = 2; i < Math.sqrt(s) + 1; i++) {
      if (f[i]) {
        // i가 남아 있는 숫자라면 이 숫자의 배수를 구한다.
        for (let j = 2 * i; j < s; j += i) {
          f[j] = false; // 배수는 소수가 아니다
        }
      }
    }

        // 소수를 결과 배열로 이동한다
    const primes: number[] = [];
    for (let i = 0; i < s; i++) {
      if (f[i]) primes.push(i);
    }

    return primes;
  } else {
    // maxValue < 2
    return []; // 입력이 잘못되면 비어 있는 배열을 반환한다.
  }
}

/* 4-8 generatePrimes.ts (리팩토링 버전) */
let crossedOut: boolean[]
export default function generatePrimes(maxValue: number) {
  if (maxValue < 2) {
    return [];
  } else {
    crossedOut = uncrossIntegerUpTo(maxValue);
    crossOutMultiples();
    const result = putUncrossedIntegersIntoResult();
    return result;
  }
}

function uncrossIntegerUpTo(maxValue: number) {
  const crossedOut = new Array(maxValue + 1).fill(false, 2);
  return crossedOut;
}

function crossOutMultiples() {
  const limit = determineIterationLimit();
  for (let i = 2; i <= limit; i++) {
    if (notCrossed(i)) crossOutMultiplesOf(i);
  }
}

function determineIterationLimit() {
  // 배열에 있는 모든 배수는 배열 크기의 제곱근보다 작은 소수의 인수다
  // 따라서 이 제곱근보다 더 큰 숫자의 배수는 제거할 필요가 없다.
  const iterationLimit = Math.sqrt(crossedOut.length);
  return iterationLimit;
}

function crossOutMultiplesOf(i: number) {
  for (let multiple = 2 * i; multiple < crossedOut.length; multiple += i) {
    crossedOut[multiple] = true;
  }
}

function notCrossed(i: number) {
  return crossedOut[i] === false;
}

function putUncrossedIntegersIntoResult() {
  const result: number[] = []
  for (let i = 2; i < crossedOut.length; i++) {
    if (notCrossed(i)) result.push(i);
  }
  return result
}

---

마무리

주석은 다른 개발자를 위한 배려라고 생각한다. 특히 코드만으로는 표현하기 어려운 목적과 의도를 나타낼 때 좋은 지침이 될 수 있다.

하지만 주석에 너무 의존하는 것은 좋지 않다. 주석은 어떤 툴로도 검증할 수 없으며, 시간이 지날수록 오히려 오해와 혼동을 불러일으킬 수 있다.

가장 좋은 것은 주석이 필요하지 않은 코드를 작성하는 것. 주석이 설명하는 것은 대부분 깔끔한 코드 구조와 명확한 네이밍으로 대체될 수 있다.

주석보단 클린코드!