Part 1, 표면적 수준에서의 개선
어떤 책이든 처음 봤을 때 보기 좋을 때가 쉽게 읽고, 이해할 수 있을 것입니다.
이처럼 처음 “표면적 수준”에서의 개선이란 처음 코드를 보았을 때 “보기 좋게” 또는 “쉽게 이해하게”할 수 있도록 이름을 짓고, 좋은 설명을 달고, 보기 좋게 정렬 하는 것을 뜻합니다.
이름에 정보 담기 🔖
변수, 함수 혹은 클래스 명을 정할 때 “좋은 이름”을 정했을 때는 생각보다 많은 정보를 담을 수 있습니다.
특정한 단어를 사용하라
Get 같은 보편적인 단어보다는 fetch, download 같은 구체적인 단어를 선택하자!
Get과 같은 지나치게 보편적인 단어를 선택한다면, 다양한 해석이 가능하기 때문에 구체적인 정보를 담기 힘듭니다.
| 단어 | 대안 |
|---|---|
| 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 |
접두사 혹은 접미사로 세부 정보를 덧붙여라
- 단위를 포함하는 값들
| 함수 | 인수 단위를 포함하게 재작성 |
|---|---|
| start(delay: Int) | delay -> delay_secs |
| createCache(size: Int) | size -> size_mb |
| throttleDownload(limit: CGFloat) | limit -> max_kbps |
| rotate(angle CGFloat) | angle -> degrees_cw |
- 중요한 속성 포함하기
| 상황 | 변수명 | 더 나은 이름 |
|---|---|---|
| 패스워드가 ‘planText’에 담겨 있고, 추가적인 처리를 하기 전에 반드시 암호화되어야 한다. | password | plaintextPassword |
| 사용자에게 보여지는 설명문(comment)이 화면에 나타나기 전에 이스케이프(escaping) 처리가 되어야 한다. | comment | unesscapedComment |
| html의 바이트가 UTF-8로 변환되었다. | html | html_utf8 |
| 입력데이터가 ‘url encoded’되었다 | data | data_urlenc |
이름은 얼마나 길어야 하는가?
- 사용범위가 넓은 변수일 경우
- 생략을 최소화하고, 구체적으로 이름을 짓자!(이름이 길어져도 좋다.)
- 사용범위가 좁은 변수일 경우
- 변수명이 작더라도, 콘텍스트 이해하기 쉬우므로 짧게 이름을 짓자.
오해할 수 없는 이름들 🧐
처음 코드를 보는 사람들은 같은 이름을 보더라도 다양한 해석을 할 수 있습니다. 그러니 이름을 지운 후에 “다른 사람들이 어떻게 해석 할 수 있을까?”를 항상 생각해 봐야 합니다.
Ex, Filter()
저도 항상 헷갈리는
filter(나만 헷갈린게 아니였네요..ㅎㅎ).위
results는 어떤 데이터 일까요?
year <= 2011인 데이터인가?year <= 2011가 아닌 데이터인가?위의 의미는 헷갈리므로 “고르는” 기능을 원한다면
select(), “제거하는” 기능을 원한다면exclude()가 더 좋을 것입니다.
경계값
범위를 가지는 값에서 경계값의 포함, 미포함에 여부를 분명하게 해줘야 합니다.
한계값(포함하지 않음)을 정의할 때에는 max, min을 붙어줍니다.
경계를 포함하는 범위에는 first와 last를 사용합니다.
- 시작 경계값을 포함, 마지막 경계값은 배제하는 범위에는 begin와 end를 사용합니다.
불리언 변수 네이밍
is,has,can,should등을 이용하여 의미를 더 명확하게 만들기!
미학
코드를 훑어보는데 걸리는 시간이 적을수록, 사람들은 코드를 더 쉽게 사용할 수 있습니다.
이를 위해 다음과 같은 세가지 원리를 이용하여 미학적으로 좋은 코드를 짜야합니다.
- 코드를 읽는 사람이 이미 친숙한, 일관성 있는 레이아웃을 사용하라.
- 비슷한 코드는 서로 비슷해 보이게 만들어라.
- 서로 연관된 코드는 하나의 블록으로 묶어라.
주석에 담아야 하는 내용 📝
주석의 목적은 코드를 처음 접하는 사람이, 코드를 짠 사람만큼 코드를 이해할 수 있도록 돕는 역할을 합니다.
주석으로 설명하지 말아야 하는 것
하지만 다음과 같은 주석은 새로운 정보를 제공 하지도 않고, 더 잘 이해하도록 도와주지 않는 가치 없는 주석이 있습니다.
코드에서 유추할 수 있는 내용
- 설명 자체를 위한 설명
- 나쁜 이름을 위한 주석 - 대신 이름을 고치자! (좋은 코드 > 나쁜 코드 + 좋은 주석)
주석으로 기록해야 하는 내용
주석은 코드를 처음 접하는 사람의 입장으로 작성을 해야 합니다.
코드가 특정한 방식으로 작성된 이유를 설명해주는 내용(감독의 설명)
코드에 담긴 결함
| 표시 | 보통의 의미 |
|---|---|
| TODO: | 아직 하지 않은 일 |
| FIXME: | 오동작을 일으킨다고 알려진 코드 |
| HACK: | 아름답지 않은 해결책 |
| XXX: | 위험! 여기 큰 문제가 있다 |
- 어떤 상수가 특정한 값을 갖게 된 ‘사연’.
명확하고 간결한 주석달기
주석은 읽은 데 추가적인 시간이 걸리므로, 항상 간결하고 명확해야 합니다.
- ‘it’이나 ‘this’같은 대명사가 여러 가지를 가리킬 수 있다면 사용하지 않는 것이 좋다.
- 함수 어떻게 구현했는지 한도내에서 명확하게 설명하자.
- 입/ 출력 예시를 보여주자.
- 많은 의미를 함축하는 단어로 주석을 간단하게 만들자.