노개북 클린코드 챌린지 #06~08

제 4장. 주석

“우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다.”

“프로그래머들이 주석을 엄격하게 관리해야 한다고 주장할지도 모르겠다. 하지만 나라면 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로, 그래서 애초에 주석이 필요 없는 방향으로 에너지를 쏟겠다.”

• 나쁜 코드에 좋은 주석을 달려고 노력하기 보단 좋은 코드를 만들자

그럼에도 필요한 좋은 주석

• 법적인 주석 : 회사 표준 등의 이유로 특정 주석이 필요한 경우
• 정보를 제공하는 주석 : 기본적인 정보를 주석으로 ㅈ제공하기
• 의도를 설명하는 주석 : 결정에 깔린 의도 설명
• 의미를 명료하게 밝히는 주석 : ex) a.compareTo(b) == -1; // a< b
• 결과를 경고하는 주석 : ex) // 여유시간이 충분하지 않다면 실행하지 마십시오.
• TODO 주석
• 중요성을 강조하는 주석
• 공개 API에서 Javadocs

나쁜 주석

• 그 주석만으로는 이해가 안되서 코드의 다른 부분을 뒤적이게 만드는 주석
• 같은 이야기를 중복하는 주석
• 오해할 여지가 있는 주석
• 의무적으로 다는 주석 : 모든 변수게 주석을 달아야 한다? 모든 함수에 Javadocs가 필요하다? 코드를 복잡하게 만들 뿐
• 이력을 기록하는 주석 : VCS가 있으니 더는 필요가 없는 주석
• 배너 - 위치를 표시하는 주석 : ex) ############ Actions ############
• 주석으로 처리한 코드 : 다른 사람들은 이유가 있어서 남겼나 싶어 지우지 않고, 그렇게 점점 쌓인다. 바로 처리하자.
• 전역 정보를 담은 주석 : 근처에 있는 코드에 대해서만 쓰자
• Too Much Info : 그 프로토콜의 역사와 세부 정보까지 다 쓸 필요가 전혀 없다
• 비공개 코드에서 Javadocs

 

제 5장. 형식 맞추기

세로 형식 맞추기

• 적절한 문서 길이를 유지하라.
  • 한 파일은 일반적으로 500줄을 넘지 않고 대부분 200줄 미만이다.
• 세로 거리로 연관성을 알 수 있게하기
  • 빈 행을 넣어 개념을 분리
  • 개념적으로 가까울 수록 근처에 배치
• 호출되는 함수를 호출하는 함수보다 나중에 배치한다.

가로 형식 맞추기

• 짧은 행이 바람직하다. 100자~120자가 넘어가면 안된다.
• 가로 정렬은 바람직하진 않다.
• 들여쓰기!