Part One 표면적 수준에서의 개선 - 2. 이름에 정보 담기

저작자 : The Art of Readable Code by Dustin Boswell and Trevor Foucher. Copyright 2012 Dustin Boswell and Trevor Foucher, 978-0-596-80229-5
번역본 : 읽기 좋은 코드가 좋은 코드다. / 한빛미디어

1. 코드는 이해하기 쉬어야 한다.

- 코드는 다른 사람이 그것을 이해하는 데 들이는 시간을 최소화하는 방식으로 작성되어야 한다.

Part One - 표면적 수준에서의 개선

2. 이름에 정보담기

• 특정한 단어 고르기
• 보편적인 이름 피하기 (혹은 언제 그런 이름을 사용해야 하는지 깨닫기).
• 추상적인 이름 대신 구체적인 이름 사용하기.
• 접두사 혹은 접미사로 이름에 추가적인 정보 덧붙이기.
• 이름이 얼마나 길어져도 좋은지 결정하기
• 추가적인 정보를 담을 수 있게 이름 구성하기

2.1 특정한 단어 고르기

이름에 정보를 담아내는 방법 중 하나는 매우 구체적인 단어를 선택하여 무의미한 단어를 피하는 것이다.

예) def GetPage(url) -> FetchPage() 혹은 DownloadPage()
     class BinaryTree { int size() ... } -> Height(), NumNode(), MemoryBytes()
     class Thread { void Stop() ...} -> Kill()

단어	대안
send	deliver, dispatch, announce, distribute, route
find	search, extract, locate, recover
start	launch, create, begin, open
make	create, set up, build, generate, compose, add, new

재치있는 이름보다 명확하고 간결한 이름이 더 좋다

2.2 tmp나 retval 같은 보편적인 이름 피하기

• 이름에 정보를 담아내는 방법 중 하나는 매우 구체적인 단어를 선택하여 무의미한 단어를 피하는 것이다.
• retval 이라는 이름은 정보를 제대로 담고 있지 않다. 대신 변수값을 설명하는 이름을 사용하라.
• tmp라는 이름은 대상이 짧게 임시적으로만 존재하고, 임시적 존재 자체가 변수의 가장 중요한 용도일 때에 한해서 사용해야 한다.
• 루프반복자를 다른 목적으로 사용하면 혼돈을 초래할 수 있다. 그렇게 하지 말자!!
• tmp, it, retval 같은 보편적인 이름을 사용하려면, 꼭 그렇게 해야 하는 이유가 있어야 한다.

2.3 추상적인 이름보다 구체적인 이름을 선호하라.

변수나 함수 혹은 다른 요소에 이름을 붙일 때, 추상적인 방식이 아니라 구체적인 방식으로 묘사하라.

2.4 추가적인 정보를 이름에 추가하기.

변수나 함수 혹은 다른 요소에 이름을 붙일 때, 추상적인 방식이 아니라 구체적인 방식으로 묘사하라.

ex) string id; -> hex_id;
     var start; -> var start_ms;

다음 표는 단위를 포함하지 않는 함수의 인수와 단위를 포함하는 더 나은 함수의 인수를 나타내고 있다.

함수	인수 단위를 포함하게 재작성
Start(int delay)	delay -> delay_secs
CreateCache(int size)	size -> size_mb
ThrottleDownload(float limit)	limit -> max_kbps
Rotate(float angle)	angle ->degress_cw

 

다음 표는 이름에 추가적인 정보를 나타내야 하는 여러 가지 상황을 보여준다.

상황	변수명	더 나은 이름
패스워드가 plaintext 에 담겨 있고, 추가적인 처리를 하기 전에 반드시 암호화되어야 한다.	password	plaintext_password
사용자에게 보여지는 설명문이 화면에 나타나기 전에 이스케이프 처리가 되어야 한다.	comment	unescaped_comment
html의 바이트가 UTF-8으로 변환되었다.	html	html_utf8
입력데이터가 url encoded 되었다.	data	data_urlenc

변수의 의미를 제대로 이해하는 것이 중요하다면 그 의미를 드러내는 정보를 변수의 이름에 포함시켜야 한다.

2.5 이름은 얼마나 길어야 하는가?

• 좁은 범위에서는 짧은 이름이 괜찮다.
• 긴 이름 입력하기 - 더 이상 문제가 되지 않는다.(단어 완성 기능 사용 : 이클립스 -> alt-/)
• 약어와 축약형
  팀에 새로 합류한 사람이 이름이 의미하는 바를 이해할 수 있다면 축약형을 사용하고 그러지 않다면 사용하지 말라
• 불필요한 단어 제거하기
  ex) ConvertToString() -> ToString(), DoServeLoop() -> ServeLoop()

2.6 이름 포맷팅으로 의미를 전달하라. 상수, 멤버변수, 지역변수 등 포맷팅을 다르게 사용하라

 

요약

• 특정 단어를 사용하라 - 예를 들어 상황에 따라 Get 대신 Fetch나 Download를 사용하는 것이 더 나을 수 있다.
• 꼭 그래야 하는 이유가 없다면 tmp나 retval과 같은 보편적인 이름의 사용을 피하라.
• 대상을 자세히 묘사하는 구체적인 이름을 이용하라 - ServerCanStart()는 CanListenOnPort()에 비해서 의미가 모호하다.
• 변수명에 중요한 세부 정보를 덧붙여라 - 예를 들어 밀리초의 값을 저장하는 변수 뒤에 _ms를 붙이거나 이스케이핑을 수행하는 변수의 앞에 raw_를 붙이는 것이다.
• 사용 범위가 넓으면 긴 이름을 사용하라 - 여러 페이지에 걸쳐서 사용되는 변수의 이름을 하나 혹은 두 개의 짧은 문자로 구성해 의미를 알아보기 힘들게 짖지 말라. 다만 적은 분량(좁은 범위)에서 잠깐 사용되는 변수명은 짦을수록 더 좋다.
• 대문자나 밑줄 등을 의미 있는 방식으로 활용하라 - 예를 들어 클래스 멤버를 로컬 변수와 구분하기 위해서 뒤에 '_'를 붙일 수 있다.