Community

개발자 99% 커뮤니티에서 수다 떨어요!

← Go back
TIL-4 주석
by leeq
#clean_code
2년 전
449


TIL (Today I Learned)

2022.02.25

오늘 읽은 범위

4장. 주석

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

  • 서론 - p68

  1. 주석은 '순수하게 선하지' 못하다. 사실상 주석은 기껏해야 필요악이다.

  2. 프로그래머들이 주석을 유지하고 보수하기란 현실적으로 불가능하니까.

  3. 진실은 한곳에만 존재한다. 바로 코드다.

  • 주석은 나쁜 코드를 보완하지 못한다 - p69

  1. 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.

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

  • 코드로 의도를 표현하라! - p70

  1. 많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.

  • 좋은 주석 - p70

  1. 의도를 설명하는 주석

  2. 결과를 경고하는 주석

  3. TODO 주석

  • 나쁜 주석 - p75

  1. 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다.

  2. 있으나 마나 한 주석을 달려는 유혹에서 벗어나 코드를 정리하라.

  3. 주석을 달아야 한다면 근처에 있는 코드만 기술하라.

  4. 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.

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

코드의 주석은 마치 스마트폰의 제품 설명서와 같다. 필요한 정보는 없으며, 그 누구도 읽지 않고, 리소스 낭비일 뿐이다. 대부분의 경우 형식상 끼워 넣는 것에 불과하다. 나의 이런 견해는 저자의 그것과 일치하는 듯하다. 이 장의 좋은 주석에 대한 설명보다 나쁜 주석에 대한 설명이 더 많은 것이 어느 정도의 반증이라고 할 수 있겠다.

주석은 없을 수록 좋다. 주석은 부연 설명이다. (일반적으로) 코드(주석을 제외한)를 통한 설명이 충분하다면 (협업자가 직관적으로 이해할 수 있다면) 부연 설명(주석)은 필요하지 않다. 이전 문장처럼 나쁜 주석들은 가독성만 저해할 뿐이다. 나도 나쁜 주석을 코드에 달기를 일삼던 때가 있었다. 클린 코드에 대한 필요성을 느끼지 못했을 무렵이었다. 코드가 너무나도 지저분해서, 주석이 없이는 도저히 무엇을 위해 어떤 input으로 어떻게 작업을 수행하는지 이해할 수 없기 때문이었다. 얼마 후, 밀려 내려오는 더티 코드를 주석으론 막을 수 없다는 걸 깨닫게 되었다. 현재는 과거처럼 주석이 능사가 아니라는 것을 알지만, 이 장을 읽고서 확신을 갖게 되었다. 주석을 작성할 시간에 코드를 고치자!

최근에는 거의 TODO 주석만을 사용하고 있다. 또는 한글로 작성된 data label들을 코드 내에서 영어로 번역하여 선언하는 경우나. TODO 주석은 꽤나 유용하다. 그리고, 대상의 윗 줄에 주석을 작성하고 있다. "프로그래머들이 주석을 유지하고 보수하기란 현실적으로 불가능"에 격하게 공감한다. 최근 IDE들이나 텍스트 에디터들은 아주 똑똑한 리팩터링 기능을 제공해주지만, 주석까지 리팩터링해주지는 않는다. 그렇기 때문에, 피치 못할 사정으로 주석을 작성해야 할 때는 대상 코드에 최대한 가까워야 한다. 그래야만 주석이 있다는 사실을 더 빨리 인지하고 수정할 테니까. 하지만 코드의 아래에 주석을 작성하자니, 경험적으로 코드와 주석이 생이별하는 경우가 많았다. 같은 라인의 끝에 작성하자니, 라인이 너무 길어져 지저분해지고 가독성이 떨어진다. 그래서 나름의 규칙으로 주석은 코드의 윗 줄로 정했다. 하지만 함수의 내부에 주석을 작성하는 것은 지양한다. 만약 꼭 그래야 한다면, 함수를 다시 짜자.

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

4장까지 읽다보니, 문득 깨달은 사실이 있다. 바로 이 책은 컴파일 언어를 기준으로 쓰여졌다는 것이다. Python과 같은 인터프리터 언어에 적용하기엔 낯선 부분도 약간씩 보인다.