나쁜 코드에 주석을 달지마라. 새로 짜라.
코드로 의도를 표현할 능력이 있다면 주석은 필요하지 않다.
주석이 필요한 상황이 오면
상황을 역전해 코드로 의도를 표현할 방법을 찾아보자.
프로그래머들이 주석을 유지하고 보수하기란 현실적으로 불가능하다.
주석은 나쁜 코드를 보완하지 못한다.
- 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가
복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
코드로 의도를 표현해라.
좋은 주석
- 법적인 주석 - 저작권 정보, 소유권 정보 등
- 정보를 제공하는 주석
- 의도를 설명하는 주석
- 의미를 명료하게 밝히는 주석
- 결과를 경고하는 주석
- TODO
- 중요성을 강조하는 주석
- 공개 API에서 Javadocs
나쁜 주석
- 주절거리는 주석
- 같은 이야기를 반복하는 주석
- 오해할 여지가 있는 주석
- 의무적으로 다는 주석
- 이력을 기록하는 주석
- 있으나 마나한 주석
- 공로를 돌리거나 저자를 표시하는 주석
- 주석처리한 코드
- HTML 주석
- 전역 정보
- 너무 많은 정보
- 비공개 코드에서 Javadocs

내가 생각하는 핵심과 해석

반성

책을 읽기 전...

오늘 업무 중에도 열심히 주석을 작성했습니다.

// 1. 선행작업1을 한다.

// 2. 선행작업2를 한다.

// 3. 본 작업을 한다.

// 4. 결과를 반환한다.

습관적으로 로직 작성 전에 작업의 순서를 주석으로 작성합니다.

그리고 작성한 주석을 토대로 로직을 작성하고

로직 작성이 완료된 후에 주석을 삭제하지 않고 그대로 남겨둡니다.

누군가가 코드를 이 코드를 참고하거나 수정해야할 때

코드를 직접 해석하지 않고 주석만으로 빠르게 이해할 수 있길 바라며...

오늘도...

저의 주석은 제가 코드로 의도를 표현하는 능력이 떨어짐을 보여주는 것이라며

책에게 혼났습니다.

혼날 일 없는 개발자가 되고 싶네요.

TIL 추천