[클린 코드] Assignment #03: TIL - 2장. 의미 있는 이름 + 책을 읽는 이유

 

📢 DAY 3
🏷️ 오늘 읽은 범위: 2장. 의미 있는 이름

🖊️ 내용 요약

소프트웨어 분야에서 이름을 짓는 경우는 빈번하게 일어나기 때문에 2장에서는 이름을 잘 짓는 규칙에 대해 소개한다. 이 장에서 소개한 규칙을 실제 코드에 적용해보면 내용이 더 오래 기억에 남을 것 같아서 지금까지 진행한 몇몇 프로젝트의 코드를 다시 살펴보며 규칙에 어긋난 내용이 있다면 어떤식으로 고치면 좋을지 고민한 내용도 추가해 보았다.

---

1. 의도를 분명히 밝혀라

이름을 짓는 대상의 존재 이유, 수행 기능, 사용 방법을 명확하게 나타내야 한다.

가격을 format할 때 필요했던 numberformat

 

음식 주문 앱 프로젝트 코드를 살펴보다가 발견했다... 가격을 format할 때 필요했던 numberformat을 당당하게 f로 선언했다... 근데 이때 기억상으로는 format을 정의하는 변수는 관행적으로 f라고 짓는다고 생각했던 것 같다. 하지만 변수명을 f가 아니라 priceformat이라고 지었다면 더 명료했을 것 같다.

 

2. 그릇된 정보를 피하라

헷갈릴만한 내용을 일부로 작성하지 않는다. 나름대로 널리 쓰이는 의미가 있는 단어를 다른 의미로 사용하면 안된다. 특수한 기술적 의미를 가진 단어를 남용하지 않는다. 흡사한 이름을 사용하지 않는다. 유사한 개념은 유사한 표기법을 사용한다. 서로 헷갈리는 문자로 변수를 사용하지 않는다.

채팅 앱을 구현할 때 사용했던 chat과 message model

 

채팅 앱을 구현할 때 채팅방을 chat으로 이름 짓고, 채팅방에서 주고 받는 대화는 message로 이름 지었었다. 이건 개발할 때도 채팅이 chat인지 message인지 스스로 엄청 헷갈렸었다... 이때는 채팅방을 영어로 chat이라고 부르는 줄 알고 잘못 지었던 것 같다. 이 때 채팅방과 채팅을 chatroom과 chat으로 지었다면 이름 때문에 헷갈리던 시간을 줄일 수 있었을 것 같다.

 

3. 의미 있게 구분하라

구분만 하려고 의미 없는 문자를 덧붙이지 않는다. 연속적인 숫자 덧붙이거나 불용어 추가하지 않는다.(ex. data, info, variable, table 등등)

바로 찾을 줄은 몰랐는데... 책 읽으면서 엄청 찔렸다.

future 타입의 데이터: _prompsData, snapshot에서 받아오 데이터: prompts

 

flutter에서 futurebuilder를 사용할 때 snapshot으로 받아오는 데이터는 코드에서 많이 사용하기 때문에 간결하게 prompts라고 짓고, future 타입의 변수는 이 변수와 구분짓기 위해 변수명에 data를 붙였었다. 하지만 이 이유도 코드를 읽어서 생각이 났다... 이럴 때는 변수명을 _prompstData가 아니라 _promptsFuture라고 짓는 게 좀 더 명확할 것 같다. (근데 변수명에 타입을 붙이는 게 좋은 건가...?)

 

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

발음하기 쉬운 이름을 써야 의사소통도 편하다.

 

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

중요한 변수를 문자 하나나 상수로 사용한다면 나중에 검색하기 어렵다.(ex. 7, e ...)

맞는 텍스트는 array의 index 2

 

맞춤법 검사 api를 썼었는데 정답 text가 array의 index 2번째 자리로 들어와서 코드를 저렇게 썼던 기억이 난다. 2라는 숫자가 직관적이지 않으니까 CORRECT_TEXT_INDEX 이라고 바꾸는 게 나았을지도 모르겠다.

 

6. 인코딩을 피하라

헝가리식 표기법, 변수 접두어 등을 사용하지 않는 게 좋다.

 

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

변수 이름을 자신이 아는 이름으로 변환해야 하는 변수는 바람직하지 않다. 문자 하나만 사용하는 변수와 본인만 아는 의미를 가진 변수는 사용하지 않는 게 좋다.

구화 어플 개발할 때 구현한 model 클래스명

 

오랜만에 이 프로젝트를 열었더니 bookmark model은 수행 기능이 이름에 명확하게 나타나서 무슨 역할을 하는지 바로 생각이 났는데, chat model과 prompt model은 어떤 기능을 하는지 기억이 나지 않았다. 코드를 읽다보니 이름을 이렇게 지은 이유가 생각이 났다. chat model은 채팅이 아니지만 채팅과 담는 내용의 형식이 비슷해 chat이라고 지었고, prompt model은 클래스 변수들이 chatgpt의 api를 이용할 때 작성하는 prompt의 내용과 비슷해 prompt라고 지었었다...직관적으로 기능을 설명하지 못해 이렇게 구구절절 설명해야 하는 이름이라면 잘못 쓴 게 맞는 것 같다. (근데 이 둘은 더 적합한 변수명이 생각나지 않는다...🙁)

 

8. 클래스 이름

명사나 명사구가 적합하다.

 

9. 메서드 이름

동사나 동사구가 적합하다. 접근자, 변경자, 조건자는 각각 set, get, is를 붙인다. overload할 때는 정적 팩토리 메서드를 사용하고, 메서드는 인수를 설명하는 이름을 사용한다.

음식 포장 주문 앱에서 발견한 코드 (또 data를 붙인 변수 발견...)

 

책에서 말하는 정적 팩토리 메서드의 예시와 Flutter에서의 Named Constructor가 비슷해 보여서 관련 코드를 찾아 보았다. 한 프로젝트에서 하나의 model에 여러 개의 Named Constructors를 사용한 적이 있다. fromJson과 fromJsonWithOptions는 인수를 설명하는 이름으로 지었는데, fromJsonForOrder는 인수를 설명하는 이름으로 짓지 않았다. 그래서 fromJsonForOrder 은 fromJson과 똑같이 json을 인수로 받는데 생성자의 이름이 달라 코드를 읽어야만 역할을 이해할 수 있었다. Named Constructor의 이름은 인수를 설명하는 이름으로 지어야 직관적으로 이해하기 쉬운 것 같다. (코드를 읽어본 결과 fromJsonForOrder는 이름을 바꿔서 해결될 문제가 아니라 주문 받은 메뉴를 위한 model을 따로 만들었어야 했다는 사실을 알게 되었다...그래도 같이 사용한다면 fromJsonForOrder의 인수 이름을 json이 아니라 order로 만들면 더 이해하기 쉬울 것 같다.)

 

10. 기발한 이름은 피하라

재미난 이름보단 명료한 이름이 좋다.

기발한 변수명이라니...생각도 못해봤다...

 

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

똑같은 개념은 동일한 이름으로 사용해야 한다.

정말 놀랍네... 이게 무슨 코드?

 

사실상 uuid와 id 모두 식별자로 사용하는 변수명인데 무슨 생각으로 uuid와 id를 같이 사용한 건지 모르겠다... 코드를 읽어보니까 menu model의 설계 자체를 잘못한 게 문제였다. menu model에 담을 내용을 다른 model로 분리했다면 모두 id로 변수명을 통일할 수 있다.

 

12. 말장난을 하지 마라

한 단어를 두 가지 목적으로 사용하지 않는다.

 

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

모든 이름을 문제 영역에서 가져올 필요는 없으며 전산 용어, 알고리즘 이름, 패턴 이름 등을 이름에 사용해도 괜찮다.

 

14. 문제 영역에서 가져온 이름을 사용하라

적절한 프로그래머 용어가 없거나 문제 영역 개념과 관련이 깊다면 문제 영역에서 이름을 가져온다.

 

15. 의미 있는 맥락을 추가하라

큰 범위에 속하는 변수는 범위 안에 포함시켜 맥락을 추가할 수 있다. 이름이 분명한 맥락을 모두 설명할 수 있다면 이름만으로도 코드를 이해할 수 있다.

 

16. 불필요한 맥락을 없애라

의미가 충분히 전달된다면 짧은 이름이 긴 이름보다 좋다.

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

Product라는 클래스가 있다고 가정하자.
다른 클래스를 ProductInfo 혹은 ProductData라 부른다면
개념을 구분하지 않은 채 이름만 달리한 경우다.
Info나 Data는 a, an, the와 마찬가지로 의미가 불분명한 불용어다. (p. 26)

변수나 함수 그리고 클래스 이름은 다음과 같은 굵직한 질문에 모두 답해야 한다. 변수(혹은 함수나 클래스)의 존재 이유는? 수행 기능은? 사용 방법은? 따로 주석이 필요하다면 의도를 분명히 드러내지 못했다는 말이다. (p. 22)

Product라는 클래스가 있다고 가정하자. 다른 클래스를 ProductInfo 혹은 ProductData라 부른다면 개념을 구분하지 않은 채 이름만 달리한 경우다. Info나 Data는 a, an, the와 마찬가지로 의미가 불분명한 불용어다. (p. 26)

이름 길이는 범위 크기에 비례해야 한다. (p. 28)

똑똑한 프로그래머와 전문가 프로그래머 사이에서 나타나는 차이점 하나만 들자면, 전문가 프로그래머는 명로함이 최고라는 사실을 이해한다. (p. 31)

하지만 때로는 프로그래머가 같은 맥락이 아닌데도 '일관성'을 고려해 add라는 단어를 선택한다. (p. 34)

좋은 이름을 선택하려면 설명 능력이 뛰어나야 하고 문화적인 배경이 같아야 한다. (p. 38)

🤔 오늘 읽은 소감 & 떠오르는 생각

이번에 주석을 보지 않은 채 코드만으로도 해석이 가능해야 좋은 코드라는 사실도 새롭게 알게 되었다. 그리고 항상 이름을 지을 때 많이 생각을 하면서 짓는다고 생각했는데 (변명), 책의 내용을 정리하면서 내 코드를 다시 읽어보니까...이름을 이상하게 지은 게 너무 많았다. 앞으로는 좀 더 명료하게 작성하도록 더 신경 써야겠다. 근데 책을 읽어도 고치지 못하는 이름도 있었는데, 대부분 내가 영어를 충분히 잘 하지 못해서 어떤 이름이 적합하지 판단을 쉽게 하지 못한 게 이유였다. 책에서 좋은 이름을 선택하려면 문화적인 배경이 같아야 한다고 했는데, 그게 이런 뜻인 것 같다. 

🔍 새로 알았거나 잘 이해되지 않는 내용

• 포트란
  과학 계산용으로 사용되는 언어
• 헝가리식 표기법
  변수나 함수의 이름에 데이터 타입을 명시하는 표기법
• 강한 타입
  다른 형끼리 형변환이 금지
• 정적 팩토리 메서드
  객체 생성의 역할을 하는 클래스 메서드
• visitor 패턴
  알고리즘을 객체 구조에서 분리시키는 디자인 패턴

😯 책을 읽는 이유

📚 참고

• https://ko.wikipedia.org/wiki/%ED%8F%AC%ED%8A%B8%EB%9E%80
• https://ko.wikipedia.org/wiki/%ED%97%9D%EA%B0%80%EB%A6%AC%EC%95%88_%ED%91%9C%EA%B8%B0%EB%B2%95
• https://velog.io/@jee/%EA%B0%95%ED%83%80%EC%9E%85%EA%B3%BC-%EC%95%BD%ED%83%80%EC%9E%85-%ED%98%B9%EC%9D%80-%EC%A0%95%EC%A0%81%ED%83%80%EC%9E%85%EA%B3%BC-%EB%8F%99%EC%A0%81%ED%83%80%EC%9E%85
• https://inpa.tistory.com/entry/GOF-%F0%9F%92%A0-%EC%A0%95%EC%A0%81-%ED%8C%A9%ED%86%A0%EB%A6%AC-%EB%A9%94%EC%84%9C%EB%93%9C-%EC%83%9D%EC%84%B1%EC%9E%90-%EB%8C%80%EC%8B%A0-%EC%82%AC%EC%9A%A9%ED%95%98%EC%9E%90
• https://ko.wikipedia.org/wiki/%EB%B9%84%EC%A7%80%ED%84%B0_%ED%8C%A8%ED%84%B4