[클린코드] 2장 의미있는 이름 with Typescript

좋은 이름으로 절약하는 시간은 좋은 이름을 짓기 위해 고민하는 시간보다 훨씬 더 크다.

이 장에서는 이름을 잘 짓는 간단한 규칙을 몇 가지 소개한다.

 

의도를 분명히 밝혀라

의도가 들어나는 이름은 코드 이해와 변경을 쉽게 만든다.

따로 주석이 필요하다면 의도가 분명하지 않다는 의미다. 이름을 짓기 위해 다음 질문에 모두 답해야 한다.

• 변수 또는 함수, 클래스의 존재 이유는?
• 수행하는 기능은?
• 사용 방법?

예시

// 🔴 Bad
const getTheme = (theList: number[][]) => {
  const list1: number[][] = [[]];
  theList.forEach((x) => {
    if (x[0] === 4) {
      list1.push(x);
    }
  });
  return list1;
};

이 코드의 문제점은 코드의 함축성에 있다. 코드의 맥락이 명시적으로 드러나지 않는다.

위 코드를 이해하기 위해서는 다음의 정보를 알고 있어야 한다.

1. theList에 무엇이 들어있는가
2. theList에서 0번째 값이 어째서 중요한가
3. 값 4는 무슨 의미인가
4. 함수가 반환하는 리스트 list1을 어떻게 사용하는가

이 정보가 코드에 드러나지 않기 때문에 독자는 이 코드가 하는 일을 짐작하기 어렵다.

이 코드는 사실 지뢰찾기 게임의 일부이다. 의미있는 이름을 사용하여 코드를 변경해보자.

// 🟢 Good
const STATUS_VALUE = 0
const FLAGGED = 4
const getFlaggedCells = (gameBoard: number[][]) => {
  const flaggedCells: number[][] = [[]];
  gameBoard.forEach((cell) => {
    if (cell[STATUS_VALUE] === FLAGGED) {
      flaggedCells.push(cell);
    }
  });
  return flaggedCells;
};

코드의 단순성은 변하지 않았지만 코드는 더욱 명확해졌다.

각 개념에 이름을 붙인것 만으로 코드가 훨씬 읽기 쉬워졌음을 알 수 있다.

 

그릇된 정보를 피하라

그릇된 단서는 코드 의미를 흐린다.

• 널리 쓰이는 의미가 있는 단어를 다른 의미로 사용하면 안된다.
  • 실제 배열 타입이 아니라면 accountList, accountArray라 명명하지 않는다.
• 서로 흡사한 이름을 사용하지 않도록 주의한다.
• 유사한 개념은 유사한 표기법을 사용한다.
  • 일관성이 떨어지는 표기법은 그릇된 정보이다.
• 많은 개발자는 코드 자동 완성 기능에 뜨는 이름만 보고 객체를 선택한다.
  • 유사한 개념이 알파벳 순으로 나오며, 각 개념 차이가 명백할 때 이 기능은 매우 유용해진다.

 

의미 있게 구분하라

같은 스코프에서 변수를 구분할 때, 연속된 숫자를 덧붙이거나 불용어를 추가하지 말 것

• 의도적인 이름과 정반대가 된다. 아무런 정보도 제공하지 못한다.
• 읽는 사람이 각 변수의 차이를 알 수 있도록 지어야 한다.
  • 🔴 ProductInfo ↔ ProductData
  • 🔴 money ↔ moneyAmount

 

발음하기 쉬운 이름을 사용하라

• 사람은 단어에 능숙하다.
• 발음하기 어려운 이름은 토론하기 힘들다.

const genymdhms = new Date() // 🔴 젠 야 무다 힘즈 값이 이상해요!
const generationTimestamp = new Date() // 🟢 Generation Timestamp 값이 이상하군요!

후자는 지적인 대화가 가능하다😂

 

검색하기 쉬운 이름을 사용하라

• 문자 하나를 사용하는 이름은 쉽게 눈에 띄지 않는다
• 검색 용이성의 관점에서 긴 이름이 짧은 이름보다 좋다.
• 간단한 메서드에서 로컬 변수는 짧아도 괜찮지만 범위가 커질 수록 이름도 길어지는 것이 좋다.

 

인코딩을 피하라

이름에 타입까지 명시할 필요는 없다.

• 문제 해결에 집중하는 것을 방해한다.
• 인코딩한 이름은 거의 발음하기 어려우며 오타가 생기기 쉽다.
• 타입이 바뀌면 변수명도 바꿔야한다.
• IDE의 발전으로 멤버 변수, 인터페이스, 타입 등을 모두 구분할 수 있다.

과거에는 컴파일러가 타입 체크를 하지 않았기 때문에 타입에 대한 단서가 필요했다.

요즘은 IDE에서 타입을 확인할 수 있고 변수를 선언한 위치와 사용하는 위치가 가까워지는 추세이다.

// 🔴 Bad
type PointType = {x: number, y: number}
interface IShape {...}

// 🟢 Good
type Point = {x: number, y: number}
interface Shpae {...}

// IDE에서 type인지 interface인지 변수인지 명시적으로 보여주기 때문에 이름에 넣지 않아도 된다.

자바스크립트같은 동적 타입 언어에서는 타입이 변하지 않을 경우 이름에 명시하는 것이 유용할 때가 있을 것으로 생각된다.

 

자신의 기억력을 자랑하지 마라

독자가 코드를 읽으면서 변수 이름을 자신이 아는 이름으로 바꿔 생각해야 한다면 그 이름은 적절하지 않다.

똑똑한 프로그래머는 변수 r의 의미를 언제나 기억한다. 하지만 전문가 프로그래머는 명료함이 최고라는 사실을 이해한다.

 

클래스 또는 객체의 이름

명사나 명사구를 사용하고 동사는 지양한다.

불용어를 사용하지 않는다. (Data, Info 등)

 

메서드 이름

동사나 동사구를 사용한다.

접근자, 변경자, 조건자에는 각각 get, set, is를 붙인다.

 

한 개념에 한 단어를 사용하라

추상적인 개념 하나당 단어 하나만 사용한다. 일관성 있는 어휘를 사용한다.

ex) fetch, retrieve, get 중 하나만 선택해 고수한다.

• 이름이 다르면 독자는 타입도 다르리라 생각한다.

 

한 단어를 두가지 목적으로 사용하지 마라

다른 개념에 같은 단어를 사용한다면 그것은 말장난에 불과하다.

같은 이름을 가진 메서드의 매개변수와 반환값의 의미가 같다면 문제가 없다. 하지만 맥락이 다른데도 일관성을 고려해 단어를 선택하는 것은 옳지 않다.

const add = (x:number, y:number) => x + y

// 🔴 Bad
const addStudent = (student: Student) => {
  rollBook.push(student)
}

// 🟢 Good
const insertStudent = (student: Student) => {
  rollBook.push(student)
}

 

해법 영역에서 가져온 이름을 사용하라

코드를 읽는 사람도 프로그래머라는 사실을 명심한다.

• 전산 용어, 알고리즘 이름, 패턴 이름, 수학 용어 등을 사용해도 괜찮다.
• 모든 이름을 문제 영역에서 가져오는 정책은 현명하지 못하다.
  • 매번 해당 도메인 전문가에게 의미를 물어야하기 때문
• 기술 개념에는 기술 이름이 가장 적합하다.
  • ex) JobQueue, historyStack

적절한 프로그래머 용어가 없다면 문제 영역에서 이름을 가져온다

해법 영역과 문제 영역을 구분할 수 있어야 한다.

문제 영역 개념과 관련이 깊은 코드라면 문제 영역에서 이름을 가져와야 한다.

 

의미 있는 맥락을 추가하라

대다수 이름은 스스로 의미가 분명하지 않다.

이럴 때 클래스, 함수, 이름 공간에 의미를 넣어 맥락을 부여한다. 모든 방법이 실패한다면 마지막 수단으로 접두어를 붙인다.

const printGuessStatistics = (candidate: string, count: number) => {
  let number: string;
  let verb: string;
  let pluralModifier: string;
  if (count === 0) {
    number = "no";
    verb = "are";
    pluralModifier = "s";
  } else if (count === 1) {
    number = "1";
    verb = "is";
    pluralModifier = "";
  } else {
    number = count.toString();
    verb = "are";
    pluralModifier = "s";
  }
  const guessMessage = `There ${verb} ${number} ${candidate}${pluralModifier}`;
  console.log(guessMessage);
};

• 함수 이름은 맥락의 일부만 제공하고 알고리즘이 나머지 맥락을 제공한다.
• 함수를 끝까지 읽어야 number, verb, pluralModifier라는 변수 세 개가 guess statistics 메시지에 사용된다는 사실이 드러난다. (독자가 직접 맥락을 유추해야 한다!)

함수를 작은 조각으로 쪼개고 세 변수가 확실하게 메시지에 속한다는 맥락을 부여해보자

모듈화는 Class 대신 파일로 분리해서 구현해보았다.

// makeGuessStatisticsMessage.ts
type MessageParts = {
  number: string;
  verb: string;
  pluralModifier: string;
};  // makeGuessStatisticsMessage 모듈 내 타입 선언만으로도 맥락이 분명해졌다.

export default function makeGuessStatisticsMessage(
  candidate: string,
  count: number
) {
  const {number, verb, pluralModifier} = createPluralDependentMessageParts(count)
  const guessMessage = `There ${verb} ${number} ${candidate}${pluralModifier}`;
  return guessMessage
    // 함수를 분리하여 메시지가 어떻게 구성되는 지 파악하기 쉬워졌다.
}

function createPluralDependentMessageParts(count: number): MessageParts {
  if (count === 0) {
    return thereAreNoLetters();
  } else if (count === 1) {
    return thereIsOneLetter();
  } else {
    return thereAreManyLetters(count);
  }
}

function thereAreManyLetters(count: number): MessageParts {
  const number = count.toString();
  const verb = "are";
  const pluralModifier = "s";
  return { number, verb, pluralModifier };
}

function thereIsOneLetter(): MessageParts {
  const number = "1";
  const verb = "is";
  const pluralModifier = "";
  return { number, verb, pluralModifier };
}

function thereAreNoLetters(): MessageParts {
  const number = "no";
  const verb = "are";
  const pluralModifier = "s";
  return { number, verb, pluralModifier };
}

 

불필요한 맥락을 없애라

• 일반적으로 짧은 이름이 긴 이름보다 좋다. 단, 의미가 분명한 경우에 한해서다
• 이름에 불필요한 맥락을 추가하지 않도록 주의한다.

같이 스터디하시는 분께서 자신의 경험을 공유해주셨다.

새로운 피쳐를 개발하는데 피쳐의 약자를 모든 모듈의 접두어로 붙혔다가 후회한 적이 있으셨다고 한다.

// src/components/[피쳐명]
// 피쳐의 약자가 XYZ라면,

// ❌ Bad
const useXYZTermsAgreement = () => {};
const useXYZProfit = () => {};

// ✅ Good
const useTermsAgreement = () => {};
const useProfit = () => {};

• 이미 피쳐 관련한 모든 코드는 [피쳐명]으로 된 폴더 내부에 위치해 있다. TTT 접두어는 불필요하게 중복된 맥락이다.
• 다른 피쳐에서 재사용하기 힘들다

---

마무리

클린코드는 Java 기반으로 설명하는 책이다.

이 책을 온전히 내 것으로 만들기 위해서는 더 큰 관점에서 저자의 의도를 파악하고, 내 주언어로 예시를 바꿔보는 과정이 필요하다고 생각했다.

스터디원 중에 리액트를 사용하시는 프론트엔드 현직자 분이 계셔서 경험을 공유하고 같이 공감하면서 더 풍부하게 이해할 수 있었다.

이번 챕터는 네이밍에서 수없는 시행착오로 습득했던 요령들을 시원하고 논리적으로 정리해주는 챕터였다.