[클린코드] 4장. 주석
노마드코더 '클린코드' 북클럽 (노개북)
앞으로 3주간 완독하는게 목표! 과연..! 이 책을 읽고 코드 리팩토링하는 스킬을 UP하면서 나만의 코드 스타일이 생겼으면 좋겠다.
책에서 기억하고 싶은 내용을 써보세요.
프로그래밍 언어 자체가 표현력이 풍부하다면 주석은 거의 필요하지 않다.
결국 코드로 의도를 표현하지 못해서 주석을 사용하는 것이다.
주석은 오래될수록 코드에서 멀어진다. 주석이 언제나 코드를 따라가지 못한다.
그래서 주석이 필요없는 방향으로 에너지를 쏟아라.
부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다.
주석은 나쁜코드를 보완하지 못한다.
표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
주석 대신 코드로 의도를 표현하라
좋은주석
아래와 같은 주석은 필요하고 유익한 주석이라고 판단한다
- 법적인 주석 : 소스 첫머리에 들어가는 저작권 정보와 소유권 정보
- 정보제공 : 추상메소드가 반환할 값을 설명하는 주석 -> 하지만 함수이름에 담는 편이 더 좋다.
- 의도설명 : 저자의 의도를 설명하는 주석 (예를 들어, 두 객체를 비교할때 어떤게 우선순위를 두는지)
- 결과경고 : 예를 들어 특정 테스트 케이스를 꺼야하는 이유를 설명하는 주석
- TODO : 필요하지만 당장 구현하기 어려운 업무를 기술한다.
- Javadocs : 공개api를 구현한다면 표준 자바 라이브러리에서 사용한 Javadocs를 작성해라.
나쁜주석
허술한 코드를 지탱하거나, 엉성한 코드를 변명하거나, 미숫한 결정을 합리화하는 단지 개발자의 독백에 불과
- 주절거리는 주석 : 주석이 코드보다 더 많은 정보를 제공하지 못한다.
- 의무적으로 다는 주석 : 모든 변수에 주석을 다는 주석
- 이력을 기록하는 주석 : 이제 코드관리 시스템이 있으니까 필요없다.
- 있으나 마나 주석 : 너무 당연한 사실이라 새로운 정보를제공하지 못한다.
- 함수나 변수로 표현할 수 있다면 주석을 달지 마라
- 위치표시 : ////////으로 위치 표시하지만, 잡음 반드시 필요할때만 써라.
- 닫는괄호에 주석 : 주석을 쓰지 말고 함수를 줄여라
- 주석으로 처리한 코드는 다 지워라!
- 너무 많은 내용 : 주석을 달아야한다면 근처에 있는 코드만 기술해라.
- 모호한 관계: 주석과 주석이 설명하는 코드 둘 사이 관계가 명확해야한다.