[클린코드] 4. 주석

딱이·2022년 7월 5일

cleancode 독서 스터디

CleanCode 스터디

목록 보기

4/13

TIL (Today I Learned)

2022.06.02

오늘 읽은 범위

4장. 주석

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

주석사용 = 코드로 의도표현 실패
→ 주석을 가능한 줄이도록 꾸준히 노력
주석은 나쁜 코드를 보완하지 못한다
코드에 주석을 추가하는 일반적인 이유 = 코드 품질이 나쁘기 때문
주석달기 << 코드 정리
코드로 의도를 표현하라!

좋은 주석 🔽

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

2. 정보를 제공하는 주석
가능하다면, 함수 이름에 정보를 담는 편이 더 좋다.
(+클래스를 만들어 코드를 옮겨주면 더 좋고 더 깔끔함.)

3. 의도를 설명 & 명료하게 밝히는 주석
인수나 반환값 자체를 명확하게 만들면 best,
인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.

4. 결과를 경고하는 주석

Ex. 특정 테스트 케이스를 꺼야 하는 이유를 설명 → 여유 시간이 충분하지 않다면 실행하지 마십시오.

요즘은 주석 대신 테스트 케이스를 꺼버림. (@Ignore 사용)

5. TODO 주석

필요하나, 당장 구현하기 어려운 업무
더 이상 필요 없는 기능을 삭제하라는 알림,
누군가에게 문제를 봐달 라는 요청,
더 좋은 이름을 떠올려달라는 부탁,
앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의

But, 어떤 용도든, 시스템에 나쁜 코드를 남겨 놓는 핑계가 되면 안됨.

6. 중요성을 강조하는 주석
대수롭지 않다고 여겨질 뭔가의 중요성을 강조.

7. 공개 API에서 Javadocs
Javadocs도 잘못된 정보 전달 가능성 있음.
ex.독자를 오도, 잘못 위치..

나쁜 주석 🔽

1. 주절거리는 주석
의미없음 → 다른 사람들에게 전달되지 않는다.

2. 같은 이야기를 중복하는 주석
(코드파악 시간 <<< 주석을 읽는 시간)
코드만 지저분하고 정신 없게 만든다.
Ex. 쓸모없고 중복된 Javadocs

3. 오해할 여지가 있는 주석
주석에 담긴 ‘살짝 잘못된 정보’로 인해
프로그래머는 코드가 돌아가는 이유를 찾느라 골머리를 앓는다.

4. 의무적으로 다는 주석
코드만 헷갈리게 만들며, 거짓말할 가능성을 높이며,
잘못된 정보를 제공할 여지만 만듦.
특별한 이유 없이 의무감으로 다는 주석은 === 시간낭비.

5. 이력을 기록하는 주석
이전에는 소스 코드 관리 시스템이 없었으니까 괜찮음.
지금은 필요 없음.

6. 있으나 마나 한 주석
:당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석.
→ 개발자가 주석을 무시하는 습관에 빠진다. 결국 코드가 바뀌면서 주석은 거짓말로 변함.
함수나 변수로 표현할 수 있다면 주석을 달지 말 것.

7. 위치를 표시하는 주석
배너 아래 특정 기능을 모아놓으면 유용한 경우도 있긴 함.
배너는 눈에 띄며 주의를 환기
뒷부분에 슬래시(/)로 이어지는 잡음은 제거하는 편이 좋다.
반드시 필요할 때만, 아주 드물게 사용하기
Ex. // Actions //////////////////////////////////

8. 닫는 괄호에 다는 주석
중첩이 심하고 장황한 함수라면 의미가 있을지도 모르지만 작고 캡슐화된 함수에는 잡음 함수를 줄이려 시도