클린 코드 TIL : 4장. 주석

오늘 TIL 3줄 요약

• 생각 / 주석을 그림 그리기의 밑그림(스케치, 구도 등) 처럼 사용하는 것은 괜찮을 것 같다. (TODO 처럼.)

  • 주석은 먼저 작성하는 것. 코드를 짜고 나면 주석은 사라지거나 제거한다!. 와 같은 감각으로.

• 책 / 독자를 고려해서 코드를 짜고, 주석을 최소화 한다. 이해는 하지만 어렵다. 왜냐하면 주석이 일반적인 구어기에 프로그래밍 언어보다 표현하고 이해하기 편하다. 코드를 그 이상으로 편하게 다룰 수 있어야 하고, 또 주석을 최소화 하는 목표를 가질 때, 코드의 퀄러티는 높아질 것이다.

TIL (Today I Learned) 날짜

• 2024-01-31(수)

오늘 읽은 범위

• 4장. 주석

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

• 나쁜 코드에 주석을 달지 마라. 새로 짜라.

• 주석은 '순수하게 선하지' 못하다. 사실상 주석은 기껏해야 필요악이다. 프로그래밍 언어 자체가 표현력이 풍부하다면, 아니 우리에게 프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면, 주석은 거의 필요하지 않으리라. 아니, 전혀 필요하지 않으리라.

• 내가 이렇듯 주석을 무시하는 이유가 무엇이냐고? 거짓말을 하니까. 항상도 아니고 고의도 아니지만 너무 자주 거짓말을 하니까. 주석은 오래될수록 코드에서 멀어진다. 오래될수록 완전히 그릇될 가능성도 커진다. 이유는 단순하다. 프로그래머들이 주석을 유지하고 보수하기란 현식적으로 불가능하니까.

• 하지만 나라면 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로, 그래서 애초에 주석이 필요 없는 방향으로 에너지를 쏟겠다.

• 진실은 한곳에 존재한다. 바로 코드다. 코드만이 자기가 하는 일을 진실되게 말한다. 코드만이 정확한 정보를 제공하는 유일한 출처다. 그러므로 우리는 (간혹 필요할지라도) 주석을 가능한 줄이도록 꾸준히 노력해야 한다.

• 하지만 명심하기 바란다. 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라는 사실을!

  • 마치 의사, 변호사 처럼?

• 앞으로 할일을 //TODO 주석으로 남겨두면 편하다.

• 나쁜 주석. 대다수 주석이 이 범주에 속한다. 일반적으로 대다수 주석은 허술한 코드를 지탱하거나, 엉성한 코드를 변명하거나, 미숙한 결정을 합리화하는 등 프로그래머가 주절거리는 독백에서 크게 벗어나지 못한다.

• 예전에는 모든 모듈 첫머리에 변경 이력을 기록하고 관리하는 관례가 바람직했다. 당시에는 소스 코드 관리 시스템이 없었으니까. 하지만 이제는 혼란만 가중할 뿐이다. 완전히 제거하는 편이 좋다.

• // Actions ////////// 극히 드물지마 위와 같은 배너 아래 특정 기능을 모아놓으면 유용한 경우도 있긴 하다. ... 그러므로 반드시 필요할 때만, 아주 드물게 사용하는 편이 좋다. 배너를 남용하면 독자가 흔한 잡음으로 여겨 무시한다.

• 주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다. 이유가 있어 남겨놓았으리라고, 중요하니까 지우면 안 된다고 생각한다. 그래서 질 나쁜 와인병 바닥에 앙금이 쌓이듯 쓸모 없는 코드가 점차 쌓여간다. ( 생략 ) 이제 주석으로 처리할 필요가 없다. 그냥 코드를 삭제하라. 잃어버릴 염려는 없다. 약속한다.

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

• 개인 프로젝트를 진행하며, 나 혼자 코드를 작성하고 읽는데도 불구하고, 책에서 이야기하는 각종 나쁜 경험을 스스로 만들어내고 또 혼란스러워 하고 있다는 사실에 놀랐다.

• 독자를 고려해서 코드를 짜고, 주석을 최소화 한다. 이해는 하지만 어렵다. 왜냐하면 주석이 일반적인 구어기에 프로그래밍 언어보다 표현하고 이해하기 편하다. 코드를 그 이상으로 편하게 다룰 수 있어야 하고, 또 주석을 최소화 하는 목표를 가질 때, 코드의 퀄러티는 높아질 것이다.

• 주석을 그림 그리기의 밑그림(스케치, 구도 등) 처럼 사용하는 것은 괜찮을 것 같다. (TODO 처럼.)

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

오늘 읽은 다른사람의 TIL

• Hoya님

  • 선정 이유

    • 궁금증이 공감되었음. 저도 궁금해요!

  • https://hoya-develop.tistory.com/entry/3-%EB%85%B8%EA%B0%9C%EB%B6%81-CleanCode-3-4%EC%9D%BC%EC%B0%A8

• Daehun Kwak

  • 선정 이유

    • return 이 하나면 너무 팍팍하다. 는 의견에 대해서 궁금하다!! 어떤 이유로 그렇게 말하는 것일까?

      • api 콜할때, 결과값을 잘 받고 싶다고 느낀 적이 있는데 그런건가?

  • https://daehun.notion.site/TIL-4-of-22-3-e5d179d1ced94108a6d78d11762b397e

• redcastle

  • 선정 이유

    • 글짓기와 유사하다는 생각에 완전 공감.

      • 그런데 글을 잘 쓰려면, 많이 읽어야하고, 좋은 글을 재밌는 글을 읽어야 한다.

      • 프로그래밍의 세계에서 다른 사람들의 코드를 재미를 위해 탐닉할 좋은 아이디어는 없을까?

  • https://caring-tick-99e.notion.site/3-6ed2330b406b4c49a4a4d29ef5dac23d