🔖 4장 : 주석
읽은 날짜 : 2024.08.27
지은이 : 로버트 C. 마틴
출판사 : 인사이트
기억하고 싶은 내용
주석은 나쁜 코드를 보완하지 못한다
- 코드만으로 의도를 표현하는 것을 우선으로 해야 한다.
- 주석이 거의 없는 코드가 복잡한 주석이 많이 달린 코드보다 좋다.
좋은 주석이란?
- 법적인 주석
- 저작권, 소유권 정보, 표준 라이선스, 외부 문서 등
- 정보를 제공하는 주석
- 표현력 있게 코드를 작성하면 필요 없어질 수 있다.
- ✅ 구현 의도를 설명하는 주석
- 인수나 반환값의 의미를 명료하게 밝히는 주석
- ✅ 결과를 경고하는 주석
- ~하지 마세요, ~해야 합니다 등
- ✅ TODO 주석
- 앞으로 할 일, 필요하지만 당장 구현하기 어려운 업무 등
- ✅ 그냥 넘어갈 수 있는 부분의 중요성을 강조하는 주석
- 공개 API의 Javadocs
나쁜 주석이란?
- 코드 내용을 그대로 설명하는 주석
- 오해할 여지가 있는 주석
- 코드보다 읽기 어렵고 잘못된 정보가 포함된 경우
- 의무적으로 다는 주석
- 모든 함수에 Javadocs를 넣을 필요는 없다.
- 비공개 코드라면 Javadocs는 굳이 필요하지 않다.
- 변경 이력을 기록하는 주석
- 버전 관리 시스템이 있기 때문에 완전히 제거하는 것이 좋다.
- 너무 당연해서 새로운 정보를 제공하지 못하는 주석
- 읽는 사람이 오히려 부주의하게 넘기기 쉽다.
- 위치를 표시하는 주석
- e.g. // Actions /////////////////////////
- 반드시 필요한 경우에만 사용해야 한다.
- 적절한 들여쓰기와 포맷팅, 함수와 변수에 의미를 부여하는 것으로 주석을 없앨 수 있다. [참고]
- 닫는 괄호에 다는 주석
- 중첩이 심하고 장황한 함수가 아니라면 의미가 없다.
- 대신에 함수를 줄이려고 시도해보자.
- 저자를 표시하는 주석
- 버전 관리 시스템으로 알 수 있기 때문에 필요하지 않다.
- 주석으로 처리한 코드
- 버전 관리 시스템으로 추적할 수 있기 때문에 과감히 삭제하는 것이 좋다.
- 너무 많은 정보를 담은 주석
- 흥미로운 역사나 관련 없는 정보
오늘 읽은 소감
오픈 소스나 코드를 잘 짜는 동료의 코드를 보면 주석이 거의 없었던 걸로 기억합니다.
코드에 의도를 담아서 작성하고, 불필요한 주석을 줄이는 것이 중요하다는 것을 알게 되었습니다.
또한 주석을 달 때는 이해하기 쉽고 명료하게, 코드 자체를 설명하지 않도록 해야겠습니다.
