클린코드 4,5장 (주석, 형식)

4장 주석

---

주석은 실패를 의미한다. 코드로 의도를 표현하지 못한 것을 만회하기 위해 주석을 사용한다. 즉, 원래는 주석 없이 코드로만 의도를 표현하는게 가장 이상적이다. 

 

심지어 주석은 보통 나쁘다. 왜냐? 코드를 변경하면서 주석을 유지보수하기란 힘든 일이고, 결국 주석은 낡아지고 잘못된 정보를 드러내게 된다.

 

그럼에도 좋은 주석이 있다. 코드로 의도를 표현하는 것이 가장 이상적이지만 현실적으로는 힘든 경우가 많다. 다음은 좋은 주석의 예이다.

 

• 정보를 제공하는 주석 : 기본적으로는 함수나 변수의 이름에 정보를 담아야 한다. 그러나 시간을 나타내는 문자열의 포맷같은 정보는 유용할 수 있다. 
• 의도를 설명하는 주석 : 프로그램의 의도가 아닌 코드를 작성한 저자의 의도는 타당하다. (저자의 의도를 코드에 담을 수는 없으니까)
• 의미를 밝히는 주석 : 

if(a.compareTo(b) == -1) // a < b

위와 같은 주석은 잘못된 정보를 달아놓을 경우에 위험이 생긴다. 그러니 주의해서 사용해야 한다.

 

• 결과를 경고하는 주석 : 메서드에 '스레드에 안전하지 못 함', 혹은 '속도가 중요한 코드에서 사용하지 말 것' 과 같은 경고를 하는 주석.

 

그 외 나머지 주석은 보통 쓸데없는 주석이다. 변수 이름이나 함수의 크기를 줄이는 등의 행위로 주석을 다는 것을 피하자.

 

 

 

5장 형식 맞추기

---

• 적절한 행 길이 (웬만하면 500줄 이내)와 가로 길이 (대충 120자)를 유지하라.
• 밀집한 코드는 세로로 가까히 놓아야 한다.
• 밀접한 개념은 한 파일에 속해야 한다 : 그렇지 않으면 수직거리가 증가한다. 함수나 변수가 정의된 코드를 찾으려 상속 관계를 거슬러 올라가게 되며 가독성이 떨어진다. (protected 변수를 피해야 하는 이유이기도 하다.)
• 변수 위치 : 지역변수는 함수 처음에 그러나 루프문을 제어하거나 루프와 관련된 경우 루프 내부나 직전에 선언하는게 좋다. 
• 인스턴스 변수 : 잘 알려진 위치에 모아놓아야 한다. C++에서는 가위 규칙으로 맨 마지막에 선언, 그 외에는 클래스 처음에 선언한다.
• 종속 함수 : 호출 관계에 있는 함수는 세로로 가까이 배치해야 한다. 
• 개념적 유사성이 있으면 코드를 가까이 배치한다. (isAlive, isDead 같은 것들..)
• 세로 순서 : 함수 호출 종속성은 아래 방향으로 유지한다. 중요한 개념을 가장 먼저 표현한다. 
• 곱셈은 공백 없이 표현하면 더 보기 좋을지도. (a * b => a*b 로) 그러나 IDE가 알아서 띄워버리니..
• 인스턴스 변수 선언부가 한 눈에 안들어오면 클래스를 쪼개는 것을 고려해보자. (클래스가 너무 크다.)
• 지향점 : 코드 자체가 구현 표준 문서가 되어야함. 또 코드가 신문 기사처럼 이름만 봤을 때 내가 올바른 모듈을 살펴보고 있는지 알아야 한다. 소스파일 첫 부분은 고차원 개념과 알고리즘을, 내려갈수록 세세한 의도를 묘사한다.