4장. 주석

주석은 잘못된 정보를 전달할지도 모른다. 

코드는 리팩토링, 기능 추가를 통해 끊임 없이 변한다. 

주석이 설명하는 기능이 삭제/수정될 수도 있다. 

기능 설명이 필요한 메소드는 클래스로 분리하여 쪼개자.

의미가 모호한 메소드/변수명은 길더라도 자세하게 바꾸자. 

/* 오늘 결석한 학생들을 구하는 함수는 아래와 같이 자세한 이름으로 개선할 수 있다 */

// bad
students.get() // 오늘 결석한 학생들

// good
students.getTodaysAbsentStudents

 

좋은 주석

1.  저작권 표시 

    -> 회사명, 라이센스 등

    -> 반복된다면 하나의 별도 파일로 관리하는 것이 더 낫다. 

 

2. 외부 라이브러리를 사용하는 과정에서 의도를 명확히 밝혀야할 경우

3. TODO 주석

    -> 그렇다고 해서, "추후 리팩토링할거니 지금 대충 만들어야지 헤헿" 을 말하며 TODO를 남발하라는 것은 아니다. 

 

나쁜 주석

1. 의미가 모호한 주석. 

 

2. 중복 주석

    ->  "this.name이 null이면 기본 값 반환한다." 라고 적어두고 또 다시 "이름이 없다면 기본 이름 반환한다"를 덧붙여 적는 경우 등.

 

3. 의무적으로 다는 주석

/**
* 오늘의 날씨를 리턴한다
* @param requestMap 
* @return String
*/

- param과 return type은 함수 선언부를 봐도 알 수 있다.  제거 필요. 

  이를 습관적으로 달다보면 함수와 일치하지 않는 엉뚱한 주석 (예. 복붙으로 생김)도 나온다 

- "날씨를 리턴한다"는 정보도 메소드 명으로 대체할 수 있다. 

 

4. 수정 이력을 기록하는 주석

    -> 소스관리 툴 (예. git)에서 버전관리 된다. 주석으로 이력, 수정자, 날짜를 남기는 대신 커밋메시지를 상세하게 적자.

 

5. 너무 당연한 사실을 말하는 주석

    -> 예. 생성자 위에 '//생성자'라고 적는 경우.

 

6. 닫는 괄호에 다는 주석

 

7. 주석으로 처리하는 코드

왜 하는지 모르겠다. gitBlame이나, 소스 로그를 통해 코드 히스토리를 파악할 수 있다.

주석으로 처리하지말고 그냥 지우자. 

 

8. HTML 주석

-> 도구를 이용하자. 코드에 남발하면 안된다. 

 

9. 전역정보

클래스 변수의 주석을 함수의 주석에 넣는 경우. -> 지양하자. 

 

10. 함수헤더

이름을 잘 짓는것으로 대체. 

 

11. 너무 많은 정보
프로그램 정책을 장황히 늘어놓는 경우가 있다. (예. 결석인 학생은 출석률에서 제외한다 등)

이런 정보는 테스트 코드에서 의도를 드러내도록 바꾸어야한다.