읽기 좋은 코드가 좋은 코드다 part1

표면적 수준에서의 개선

2. 이름에 정보담기

• 특정한 단어 고르기

  • 매우 구체적인 단어를 선택하여 무의미한 단어를 피한다
  • ex. getPage 보단 FetchPage 또는 DownloadPage

• 꼭 그래야 하는 이유가 없다면 tmp나 retval 같은 보편적인 이름 피하기

• 대상을 자세히 묘사하는 구체적인 이름을 사용하라

  • serverCanStart()는 canListenOnPort()에 비해서 의미가 모호하다

• 변수명에 중요한 세부 정보를 덧붙여라

  • 밀리초의 값을 저장하는 변수 뒤에 _ms를 붙인다.

• 사용 범위가 넓으면 긴 이름을 사용하라

  • 여러 페이지에서 걸쳐서 사용되는 변수의 이름을 하나 혹은 두 개의 짧은 문자로 구성해 의미를 알아보기 힘들게 짓지 말라

• 대문자나 밑줄 등을 의미있게 사용하라

  • 클래스 멤버를 로컬 변수와 구분하기 위해 뒤에 _를 붙일 수 있다.

3. 오해할 수 없는 이름들

• 언제나 의미가 오해되지 않는 이름이 최선의 이름

  • 상한과 하한을 정할 때 max_와 min_을 앞에 붙이면 좋은 접두사 역할을 한다.
  • 경계를 포함한다면 first, last
  • 경계의 시작만 포함하고 마지막은 배제한다면 begin과 end

• 사람들이 get()은 가벼울 것이라고 생각하기 때문에 무겁다면 사용하지 말 것

4. 미학

• 누구나 미학적으로 보기 좋은 코드를 읽고 싶어한다.

• 코드를 일관성 있게, 의미 있는 방식으로 정렬하여, 읽기 편하고 빠르게 만들 수 있다.

• 여러 블록에 담긴 코드가 모두 비슷한 일을 한다면, 실루엣이 동일하게 만들어라

  • new TCPConncetionSimulator(500       , 80, 200, 1)
  • new TCPConncetionSimulator(45000   , 80, 200, 1)

• 코드 곳곳을 열로 만들어서 줄을 맞추면 코드를 한 눈에 훑어보기 편하다

• 메소드를 활용하여 불규칙성을 제거하라

• 코드의 한 곳에서 A, B, C 순서대로 언급되고 있으면, 다른 곳에서 B, C, A와 같은 식으로 언급하지 말라.

• 빈 줄을 이용하여 커다란 블록을 논리적인 문단으로 나누어라

• 일관성 있는 스타일은 올바른 스타일 보다 중요하다.

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

• 주석을 다는 목적은 코드를 작성하는 사람이 알고 있는 정보를 코드를 읽는 사람에게 전달하는 것이다

• 설명하지 말아야 하는 것

  • 코드 자체에서 빨리 도출될 수 있는 사실
  • 나쁘게 작성된 코드를 보정하려고 애쓰는 주석. 그렇게 하는 대신 코드를 수정하라

• 기록해야 하는 주석

  • 코드가 특정한 방식으로 작성된 이유를 설명
  • 코드에 담긴 결함
  • 어떤 상수가 특정한 값을 갖게 된 사연

• 자신이 코드를 읽는 입장에서 생각

  • 읽는 사람 입장에서 어떻게 생각할지 예측해보고, 주석 추가
  • 평범한 사람이 예상하지 못할 특이한 동작을 기록
  • 파일이나 클래스 수준 주석에서 큰 그림을 설명하고 각 조각이 어떻게 맞춰지는지 설명
  • 블록별로 주석을 달아 나무만 보고 숲은 못 보는 실수를 저지르지 말 것

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

• ‘it’이나 ‘this’ 같은 대명사가 여러 가지를 가리킬 수 있다면 사용하지 않는 것이 좋다

• 함수의 동작을 실제로 할 수 있는 한도 내에서 최대한 명확하게 설명

• 신중하게 선택된 입/출력 예(코너케이스)로 주석을 서술

• 코드가 가진 의도를 너무 자세한 내용이 아닌 높은 수준에서 개괄적으로 설명

• 같은 줄에 있는 주석으로 (예. /* arg = /* ….)와 같은 방식으로 의미가 불분명한 함수의 인수를 설명하라

• 많은 의미를 함축하는 단어(예. heuristic, brute-force…)로 주석을 간결하게 만들어라