클린코드: 4장 주석

오늘 TIL 3줄 요약

• 주석은 필요악이다.

• 코드만이 정확한 정보를 제공하는 유일한 출처다.

• 함수나 변수로 설명할수 있다면 구지 주석을 달지 말아라. 주석을 달고 싶다면 해당 코드의 개선을 한 번 더 생각해봐라.

TIL (Today I Learned) 날짜

2022. 01. 31

오늘 읽은 범위

4장 주석

책에서 기억하고 싶은 내용을 써보세요.

주석은 필요악이다. → 코드로 의도를 표현하지 못해 사용하는 것 → 충격

주석과 코드의 동기화가 유지되지 못할경우의 부작용을 의미

코드만이 정확한 정보를 제공하는 유일한 출처다.

주석은 나쁜 코드를 보완하지 못한다. 코드만으로 의도롤 표현해라.

좋은 주석

• 법적인 문구

• 정보를 제공하는 주석

# 추상 메서드가 반환할 값 설명
//테스트 중인 Responder 인스턴스를 반환한다. 
protected abstract Responder reponderInstance()

• 결과를 경고하는 주석: 예) 특정 테스트 케이스를 꺼야 하는 이유 설명

• TODO 주석 → 극공감

• 중요성을 강조하는 주석: 특정 코드 영역 강조 이유

나쁜 주석

• 주절주절

• 같은 내용 반복: 주석은 더 많은 정

• 오해의 여지가 있는 주석

• (변경) 이력을 기록하는 주석 → stupid

• 있으나 마나 한 주석 → 이미 코드로 다 해석되는데…

함수나 변수로 설명할 수 있다면 구지 주석을 달지 말아라.

코드가 길어서 닫는 괄호에 주석을 다는 대신 함수를 줄이려고 노력해라.

주석으로 처리하는 코드는 아예 삭제해라.→ 재활용은 소스코드 관리시스템을 활용해라. → 나쁜습관

비공개 코드에서 javadocs를 사용한다고 javadocs 주석을 사용할 경우 코드만 산만해 진다.

오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요

주석은 말 그대로 풀이글이다. 소스를 이해하기 쉽게 쓰는게 clean code인데 여기에 주석을 다는게 어찌보면 말이 안된다. 하지만 경고나 강조 등 부가설명이 필요한 경우도 분명 있다.

궁금한 내용이 있거나, 잘 이해되지 않는 내용이 있다면 적어보세요.

없었음

오늘 읽은 다른사람의 TIL

• frontend님의 TIL (url 링크)