이 글은 블로그 UI를 확인하기 위한 샘플 글입니다. 긴 제목과 본문, 한글 제목, 중복 제목의 표시를 확인하기 위해 작성했으며 일반적인 원칙만 다룹니다.
코드는 작성하는 시간보다 읽히는 시간이 훨씬 깁니다. 이름은 코드를 읽는 사람이 가장 먼저 마주치는 정보이므로, 좋은 이름 하나가 주석 여러 줄보다 많은 것을 전달하기도 합니다. 이 글에서는 이름을 정할 때 자주 도움이 되는 습관을 몇 가지로 나누어 살펴봅니다.
의도를 드러내는 이름
이름은 값이 어떻게 만들어졌는지보다 무엇을 뜻하는지를 설명해야 합니다. data, info, result 같은 범용 이름은 거의 모든 값에 붙일 수 있어서 정보를 주지 못합니다.
// 무엇을 뜻하는지 알기 어렵다.
const list = items.filter((item) => !item.draft);
// 값의 의미가 드러난다.
const publishedPosts = posts.filter((post) => !post.draft);
단위와 기준을 함께 적기
시간, 거리, 금액처럼 단위가 있는 값은 이름에 단위를 포함하면 실수가 줄어듭니다.
| 모호한 이름 | 명확한 이름 |
|---|---|
timeout |
timeoutMs |
size |
fileSizeBytes |
date |
publishedAtUtc |
price |
priceWithoutTaxKrw |
도메인 용어를 일관되게
같은 개념을 파일마다 다른 단어로 부르면 읽는 사람은 두 개념이 다른 것인지 고민하게 됩니다. 예를 들어 한 곳에서는 post, 다른 곳에서는 article, 또 다른 곳에서는 entry라고 부르면 셋의 차이를 찾아보느라 시간을 쓰게 됩니다.
용어집 만들기
팀에서 자주 쓰는 용어를 짧은 표로 정리해 두면 새로 합류한 사람도 같은 단어를 사용할 수 있습니다.
의도를 드러내는 이름
이 섹션은 앞의 제목과 같은 이름을 사용합니다. 같은 제목이 여러 번 나올 때 목차 링크와 앵커가 서로 다른 위치를 가리키는지 확인하기 위한 샘플입니다. 실제 글에서는 같은 제목을 반복하지 않는 편이 읽기 쉽습니다.
불리언과 함수 이름
불리언 값은 is, has, can, should 같은 접두어로 질문 형태를 만들면 조건문이 문장처럼 읽힙니다.
if (isDraft && !canPreviewDrafts) {
return;
}
함수는 동작을 나타내는 동사로 시작하고, 반환값의 의미가 드러나도록 합니다. getPosts는 조회를, createPost는 생성을, validatePost는 검증을 떠올리게 합니다. 이름과 실제 동작이 다르면 호출자는 함수 내부를 직접 읽어야 하므로 이름이 주는 이점이 사라집니다.
이름이 길어질 때
이름이 지나치게 길어진다면 함수나 변수가 너무 많은 일을 하고 있다는 신호일 수 있습니다. 이때는 이름을 줄이기보다 책임을 나눌 수 있는지 먼저 살펴봅니다.
짧은 이름이 항상 좋은 것은 아닙니다. 사용 범위가 좁으면 짧게, 넓으면 구체적으로 짓는다는 기준이 대부분의 상황에서 잘 맞습니다.
정리
- 값의 의미와 단위를 이름에 드러냅니다.
- 같은 개념에는 같은 단어를 사용합니다.
- 불리언은 질문 형태로, 함수는 동사로 시작합니다.
- 이름이 어색하게 길어지면 책임을 다시 살펴봅니다.
이름은 한 번에 완벽하게 정하기 어렵습니다. 코드를 읽다가 더 나은 이름이 떠오르면, 관련 테스트가 있는 범위에서 조금씩 고쳐 나가는 것으로 충분합니다.
