📓 읽기 좋은 코드가 좋은 코드다. || part1. 표면적 수준에서의 개선

**[읽기 좋은 코드가 좋은 코드다.]**를 보고 메모한 부분을 정리했습니다.

목차

1. 코드는 이해하기 쉬워야 한다. ⇒
2. 이름에 정보 담기 ⇒
3. 오해할 수 없는 이름들 ⇒
4. 미학 ⇒
5. 주석에 담아야 하는 대상 ⇒
6. 명확하고 간결한 주석 달기 ⇒

---

서론
좋은 코드는 무슨 일이 일어나고 있는지를 빠르게 전달해준다.
사용하기에도 즐겁고,
자신에게도 더 좋은 코드를 만들어야 하겠다는 욕구를 불러일으키기도 한다.

---

---

PART 1 ) 표면적 수준에서의 개선

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

1. 코드는 다른 사람이 그것을 이해하는 데 들이는 시간을 최소화하는 방식으로 작성되어야 한다.
   ⇒ 바로 인지 가능하도록
   time-til-understanding
2. 분량이 적으면 항상 더 좋은가?
   더 분량이 적은 코드로 똑같은 문제를 해결할 수 있다면 그것이 더 낫다.
3. 이해를 위한 시간은 다른 목표와 충돌되는가?
   정리가 되지 않은 코드를 고치고 싶을 때는
   뒤로 한걸음 물러나서 스스로에게 물어보는 게 중요하다.
   이 코드는 이해하기 쉬운가?

1-1. 표면적 수준

• 좋은 이름을 짓고,
• 좋은 설명을 달고
• 코드를 보기 좋게 정렬하는 따위를 의미

⇒ 이런 수정은 코드를 리팩토링하거나 프로그램이 동작하는 방식을 바꾸지 않고 그 자리에서 곧바로 만들 수 있기 때문에 수정 반영이 쉽다.
⇒ 코드베이스를 흔드는 행위이므로 결과적으로 작성하는 모든 코드에 영향을 줄 수 있다.

---

2. 이름에 정보 담기

변수, 함수, 혹은 클래스 명을 결정할 때
⇒ 이름에 정보를 담아내라

2-1. 특정한 단어 고르기

2-1.1 보편적인 단어 피하기

get은 지나치게 보편적이다.

• fetch
• download

2-1-2. 더 화려한 단어 고르기

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-1-3. 명확하고 간결한 이름이 더 좋다.

---

2-2. (tmp, retval, foo같은)보편적인 이름 피하기 (혹은 언제 그런 이름을 사용해야 하는지 깨닫기)

• tmp, retval(: 반환된 값), foo 같은 이름은
  내 머리로는 이름을 생각해낼수 없어요..
• 더 좋은 이름은
  : 변수의 목적이나 담고 있는 값을 설명해주어야한다.
• tmp : 변수 목적 자체가 코드 몇 줄에서만 사용하는
  임시저장소의 역할을 할 경우에는 사용해도 ok
• 루프반복자
  • i, j, iter, it 인덱스나 루프 반복자로 사용된다.
  • 배열이름과 + 인덱스를 합친 반복자로 사용하면 좋다.

    for(let i = 0; i < clubs.size(); i++)
      for(let j = 0; j < clubs[i].members.size(); j++)
        for(let k = 0; k < users.size(); k++)
          if(clubs[i].members[k] == users[j])
              cout << "user[" << j << "] is in club["<< i <<"]" <<endl;

  • i, j, k보다는 ⇒ club_i, members_i, users_i
  • 혹은 ci, mi, ui
• tmp, it, retval 같은 보편적인 이름을 사용하려면,
  꼭 그러게 해야하는 이유가 있어야 한다.

---

2-3. 추상적인 이름 대신 구체적인 이름 사용하기

---

2-4. 접두사 혹은 접미사로 이름에 추가적인 정보 덧붙이기

2-4-1. 단위를 포함하는 값들 (ex. 밀리세컨즈 : ~`_ms`)

변수가 시간의 양이나 바이트의 수와 같은 측정치를 담고 있다면,
⇒ 변수명에 단위를 포함시키는 게 도움이 된다.

const start = (new Date()).getTime();
...
const elapsed = (new Date()).getTime() - start;
document.writeIn("Load time was: " + elapsed + "seconds");


/** 위보다는 아래 **/


const start_ms = (new Date()).getTime();
...
const elapsed_ms = (new Date()).getTime() - start_ms;
document.writeIn("Load time was: " + elapsed_ms + "seconds");

2-4-2. 다른 중요한 속성 포함하기 (ex. 인코딩된 data : data_urlenc)

• 보안 취약한, 불안전함을 인지하고 싶을 때
  • untrustedUrl / unsafeMessageBody …
    ⇒ 안전하게 만드는 함수 호출 후에는
    ⇒ trustedUrl, safeMessageBody에 담는다.
• 변수의 의미를 제대로 이해하는 것이 중요한 상황일때 사용하긔
• 예시
  1. 패스워드가 plaintext에 담겨 있고, 추가적인 처리를 하기 전에 반드시 암호화되어야 한다.
  • password 보다는 ⇒ plaintext_password
  2. 사용자에게 보여지는 설명문이 화면에 나타나기 전에 이스케이프 처리가 되어야한다.
  • comment 보다는 ⇒ unescaped_comment
  3. html의 바이트가 UTF-8으로 변환되었다.
  • html ⇒ html_utf8
  4. 입력데이터가 url encoded 되었다.
  • data 보다는 ⇒ data_urlenc

---

2-5. 이름이 얼마나 길어져도 좋은지 결정하기

• 좁은 범위에서는 짧은 이름이 괜찮다.

2-5-1. 약어와 축약형

• 특정 프로젝트에 국한된 의미를 가진 약어 사용은 좋은 생각이 아니다.

• 팀에 새로 합류한 사람이 이름이 의미하는 바를 이해할 수 있을까?

• 축약할 때는 보편적인 것은 괜찮다.

• string 대신 str, evaluation 대신 eval

2-5-2. 불필요한 단어 제거하기

• convertToString()보다는 ToString()
• DoServeLoop()보다는 ServeLoop()

---

2-6. 추가적인 정보를 담을 수 있게 이름 구성하기

< 다른 포맷팅 **관습** >

1. jQuery 함수 호출시 jQuery의 결과를 저장하는 변수 앞에 $ 붙이기
   

   var $all_images = $("img");

2. 밑줄로 id안에는 단어를 구분하고, 대시로 클래스 안에 있는 단어를 구분 할 수 있다.
   

   <div id="middle_column" class="main-content"> ...

---

---

3. 오해할 수 없는 이름들

본인이 지은 이름을
**’다른 사람들이 다른 의미로 해석할 수 있을까?’**라는 질문을 던져보며
철저하게 확인해야 한다.

Filter()

• 고르는 행위인지 제거하는 행위인지 모호하다.
  ⇒ 보편적인 뜻을 갖고 있는 단어를 최대한 사용을 자제하자.
• select()나 exclude()

접두어**

• 경계를 포함하는 한계값을 다룰 때는 min과 max를 사용하라
• 경계를 포함하는 범위에는 first와 last를 사용하라
• 경계를 포함하고/배제하는 범위에는 begind과 end를 사용하라
• 불리언 변수에 이름 붙이기
  • is / has / can / should
• 사용자의 기대에 부응하기
  • get*() : 가벼운접근자(lightweight accessors)로서 단순히 내부 멤버를 반환한다고 관행적으로 생각한다.
• 이름을 짓기 위해서 복수의 후보를 평가하기
  • 예 ) template, reuse, copy, inherit

---

---

4. 미학

좋은 소스 코드는 ‘눈을 편하게’ 해야한다.

• 코드의 열을 맞춰라

• 의미 있는 순서를 선택하고 일관성 있게 사용하라
  ⇒ 개인적인 기준이 있으면 좋을듯
  ⇒ 중요한 것 먼저 등등..

• 선언문을 블록으로 구성하라

  • 우리의 뇌는 자연스럽게 그룹과 계층구조를 따라서 동작하므로,
    코드를 이런 방식으로 조작하면 코드를 읽는 데 도움을 준다.

• 코드를 **문단**으로 쪼개라

  • 문단 첫줄에는 주석으로 사용한다.

• 핸들러, 헬퍼함수

  • 핸들러
    이벤트에 응답해서 호출되는 함수를 이벤트 핸들러(이벤트 리스너)라고 합니다.

  • 헬퍼함수
    함수를 재사용할 수 있는 헬퍼함수

---

---

5. 주석에 담아야 하는 대상

5-1. 설명하지 말아야 하는 것

• 무가치한 주석은 달지 말자
  • 코드에서 빠르게 유추할 수 있는 내용은 주석으로 달지 말자
  • 즉, 코드를 읽으면 무슨 일을 수행하는지 알 수 있으면..
  • 설명 자체를 위한 설명은 달지 말자
• 나쁜이름에 주석을 달지마라!! ⇒ 대신 이름을 고쳐라
  • 좋은 코드 > 나쁜코드 + 좋은 주석

5-2. 코딩을 행하면서 머릿속에 있는 정보를 기록하기

1. 감독의 설명을 포함하라
   중요한 통찰은 기록하자.

   // 이 클래스는 점점 엉망이 되어가고 있다. 어쩌면 'ResourceNode' 
   // 하위 클래스를 만들어서 정리해야할지도 모르겠다.

2. 코드에 있는 결함을 설명하라

   // TODO: 더 빠른 알고리즘을 사용하라.
   // TODO(더스틴): JPEG말고 다른 이미지 포맷도 처리할 수 있어야 한다.

• 코드가 불완전 할 때는 개선 아이디어를 설명하는 것도 좋다.
• 널리 사용되는 표시
  • TODO: 아직 하지 않은 일
  • FIXME: 오작동을 일으킨다고 알려진 코드
  • HACK: 아름답지 않은 해결책
  • XXX: 위험! 여기 큰 문제가 있다
  • TextMate: ESC

3. 상수에 대한 설명

• 그 상수가 무엇을 하는지, 그것이 왜 특정한 값을 갖게 되었는지 ‘사연’이 존재하기 마련
• 사연을 주석에 남기면 좋다. 명확한 변수명이면 구지 안붙여도 됨.

5-3. 코드읽는 사람의 입장에서 필요한 정보가 무엇인지 유추하기

• 나올 것 같은 지문 예측하기
• 사람들이 쉽게 빠질 것 같은 함정을 경고하기

5-3-1. 큰 그림에 대한 주석

팀에 새롭게 합류한 사람들은 ‘큰 그림’을 이해하는 데 어려움을 겪는다. 클래스들이 어떻게 상호작용하고, 전체 시스템에서 데이터가 어떻게 흘러 다니고, 출발점이 어디인지 등을 파악해야한다.

• 이는 **상위 수준 주석**에 포함되어야 한다.
• 파일 수준의 주석의 설명은
  • 파일 시스템에 편리한 인터페이스를 제공하는 헬퍼 함수들을 담고 있다.
  • 파일의 퍼미션과 다른 자세한 세부 사항을 처리한다.

5-3-2. 요약 주석

• 함수가 수행하는 기능의 글머리 요약 역할을 수행할 수 있다.
• 주석을 보고 요점을 파악할 수 있다.

  def GenerateUserReport():
  	# 이 사용자를 위한 lock을 얻는다.
  	...
  	# 데이터베이스에서 사용자의 정보를 읽는다.
  	...
  	# 정보를 파일에 작성한다.
  	...
  	# 사용자를 위한 lock을 되덜려 넣는다.

---

6. 명확하고 간결한 주석 달기

• 주석을 간결하게 하라
• 모호한 대명사는 피하라
• 엉터리 문장을 다듬어라
• 함수의 동작을 명확하게 설명하라
• 코너케이스를 설명해주는 입/출력 예를 사용하라
  • 예시를 주석에 적는 것도 좋다.
  • 인자로 어떤 데이터가 들어가고 (입력)
    어떤 데이터를 반환하는지를 적으면 된다. (출력)
• 코드의 의도를 명시하라 → 버그를 잡을 수 있다.
• 이름을 가진 함수 파라미터 주석
• 정보 축약형 단어를 사용하라
  • 경험적인, 주먹구구식, 순진한 해법과 같이 다양한 의미를 함축하는 단어나 표현이 많다.