[Clean Code] 3장 주석

🚨 클린 코드 책에 대한 요약본입니다. 포스팅을 보고 간질간질한 구석이 있다면 꼭 책을 보길 추천드립니다.

 

책 첫 장에는 이런 말이 나온다. 클린 코드라는 책을 읽을 때는 "수학의 정석"처럼 밑줄을 그어가며 익혀야 하는 책이다.

나도 21년도에 한 번 책을 읽었으나 1년이 지난 대부분의 내용이 휘발되어 다시 읽어보며 내용을 정리해보려고 글을 쓰게 되었다.

클린 코드 1. chapter에 가장 많이 나와 있는 말은 "깨끗한 코드"이다. 깨끗한 변수, 깨끗한 함수, 깨끗한 클래스 등

사람이 읽기 쉽고, 이해하기 쉽고, 유지 보수하기 쉬운 코드는 어떤 코드인가에 대해 서술하는 책이다.

 

지난 1년간 나는 개발을 하며  마구잡이로 개발을 했다. 

구글링을 통해 코드를 복붙 하는 일도 많았고, 일단 돌아가기만 하는 코드를 만들었다. 

회사 코드자체가 엉망이라는 핑계로 나도 변수명에 크게 생각을 하지 않았고, 중복되는 코드들을 심었다.

코드 몽키가 되어 있는 나 자신의 모습에 양심이 찔려 해당 책을 다시 읽게 되었다.

 

 

⬇️ 다른 글 보러 가기

 

2022.11.28 - [Clean Code] 1장 의미 있는 이름

2022.11.28 - [Clean Code] 2장 함수

 

3장: 주석

---

'주석은 언제나 실패를 의미한다'

'주석은 오래될수록 코드에서 멀어진다. 프로그래머가 주석을 유지 보수할 일이 없기 때문이다.'

"주석은 나쁜 코드를 보완하지 못한다."

코드에 주석을 다는 일반적인 경우는 코드 품질이 나쁘기 때문이다.

표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가 복잡하고 어수선한 주석이 많이 달린 코드보다 훨씬 좋다.

 

 

 

"좋은 주석"

주석은 정말 웬만하면 달지 않는다. 

하지만 잘만 이용한다면 유익하게 사용할 수 있다고 한다.

아래의 예시들을 참고해서 주석을 사용할 때를 알아보자.

 

법적인 주석

각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보는 필요하고 타당하다.

 

예)

//Copyright C 2022 by object chlcken, Inc. All rights reserved.

 

정보를 제공하는 주석

때로는 기본적인 정보를 주석으로 제공하면 편리하다. 

예를 들어 다음 주석은 추상 메서드가 반환할 값을 설명한다.

 

//테스트 중인 Responder 인스턴스를 반환한다.
protected abstract Responder responderInstance();

 

의도를 설명하는 주석

때로 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다. 

 

 

 

//TODO 주석

해야 할 일에 대해 남겨놓는 주석

당장 구현하기 어려운 업무를 기술한다. 

누군가에게 문제를 봐달라는 요청, 더 좋은 이름을 떠올려 달라는 부탁, 앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의 등에 유용하다.

 

 

중요성을 강조하는 주석

자칫 대수롭지 않게 여겨질 뭔가의 중요성을 강조하기 위해 주석을 사용한다.

String listitemContent = match.group(3).trim();
// 여기서 trim은 중요하다. trim 함수는 문자열 시작 공백을 제거한다.
// 문자열에 시작 공백이 있다면, 다른 문자열로 인식되기 때문이다.
new ListItemWidget(this, listItemContent, this.level +1);
return buildList(text.substring(match.end()));

 

 

 

"나쁜 주석"

주절거리는 주석

특별한 이유 없이 의무감으로 혹은 프로세스에서 하라니까 하는 주석은 잘못된 주석이다.

 

 

이력을 관리하는 주석 

2022.07.01 생성

2022.07.01 수정

2022.07.01 삭제 기능 추가 등과 같은 주석은 달 필요가 없다.

 

 

있으나 마나 한 주석

/**
* 기본생성자
*/
protected AnnualDateRule(){
}

 

 

 

결론은 주석을 함수나 변수로 표현할 수 있다면 달지 말고, 그냥 웬만하면 주석을 달지 말자.