오늘 TIL 3줄 요약

• 나쁜 코드에 주석을 달지 마라. 새로 짜라. - 브라이언 W. 커니핸, P.J. 플라우거 (p.68)

• 때때로 주석 없이는 자신을 표현할 방법을 찾지 못해 할 수 없이 주석을 사용한다. 그래서 주석은 반겨 맞을 손님이 아니다. (p.68)

• 주석이 코드에서 분리되어 점점 더 부정확한 고아로 변하는 사례가 너무도 흔하다. 코드만이 정확한 정보를 제공하는 유일한 출처다. 그러므로 우리는 (간혹 필요할지라도) 주석을 가능한 줄이도록 꾸준히 노력해야 한다. (p.68, p.69)

TIL (Today I Learned) 날짜

2024.08.27(화) ~ 2024.08.28(수)

오늘 읽은 범위

• 4장. 주석

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

• 좋은 주석

  1. 의미를 명료하게 밝히는 주석

     • 주석이 올바른지 검증하기 쉽지 않다. 이것이 의미를 명료히 밝히는 주석이 필요한 이유인 동시에 주석이 위험한 이유이기도 하다. 그러므로 위와 같은 주석을 달 때는 더 나은 방법이 없는지 고민하고 정확히 달도록 각별히 주의한다. (p. 73)

• 나쁜 주석

  1. 같은 이야기를 중복하는 주석

     • 헤더에 달린 주석이 같은 코드 내용을 그대로 중복한다. (p.77)

  2. 의무적으로 다는 주석

     • 모든 함수에 javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다. (p.80)

  3. 위치를 표시하는 주석

     • 너무 자주 사용하지 않는다면 배너는 눈에 띄며 주의를 환기한다. 그러므로 반드시 필요할 때만, 아주 드물게 사용하는 편이 좋다. (p.85)

  4. 공로를 돌리거나 저자를 표시하는 주석

     • 위와 같은 정보는 소스 코드 관리 시스템에 저장하는 편이 좋다. (p.86)

  5. 전역 정보

     • 주석을 달아야 한다면 근처에 있는 코드만 기술하라. (p.88)

  6. 함수 헤더

     • 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다. (p.89)

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

• 주석을 세세하게 작성하는 편인데 어느 정도로 자세히 써야 할지 늘 고민이 많았던 터라 이번 장의 내용이 기대됐었다. 오늘은 뼈를 많이 맞았다. 좋은 주석에 해당하는 부분은 조금만 신경 쓰면 될 것 같은데, 나쁜 주석에 해당하는 부분 중에 몇 가지 아쉬운 게 있었다.

  • 하나의 함수에서 여러 작업을 수행할 때, 각 작업마다 주석으로 코드에 대한 설명을 작성해 왔다. 현재 진행 중인 프로젝트에서는 한 단계 더 나아가 분기/반복문마다 설명하는 주석을 작성하고 있었다. 책에서 말하는 ‘같은 이야기를 중복하는 주석’과 ‘함수나 변수로 표현할 수 있는 주석’에 해당한다고 생각했다.

  • '공로를 돌리거나 저자를 표시하는 주석'도 꾸준히 작성하고 있었는데, 소스 코드 관리 시스템에 저장하면 되니 불필요하다는 의견에 깊이 공감했다. VSCode에 extension 설치를 해서 파일마다 히스토리를 확인할 수 있고, 코드 각 라인마다 가장 최근에 누가 언제 변경했는지 알 수 있기 때문이다. 게다가 여럿이서 함께 작업하는 경우에는 코드를 최초로 작성한 사람이 저자로서 이름을 남겨 놓지만 다른 사람이 수정하거나 추가한 부분에 대해서는 책임질 수 없기 때문에 주석의 의미가 모호해지기도 한다.

• 방법을 몰랐을 때는 모르니까 그럴 수 있지~ 하겠지만 이제는 방법을 알아버려서 어쩔 수가 없다. 꾸준히 의식하며 개선해 보자!

나의 최애 북틸

• https://nomadcoders.co/community/thread/10149

  • 1장에서 내가 중요하게 생각했던 내용과 거의 겹치지 않는데, 핵심을 잘 정리하셨다는 생각이 들었다. 깨끗한 코드란 무엇인가에 대해 또 다른 시각으로 되새길 수 있어서 좋았다.

• https://nomadcoders.co/community/thread/10167

  • 어렴풋이 이해하고 넘어갔던 출력 인수를 피해야 한다는 내용에 대해 예로 들어주신 JavaScript의 기본 메서드들 몇 가지를 통해 확실히 이해할 수 있었다.

  • 하나의 역할만 수행하는 함수는 프로그래머라면 당연히 생각해 왔을 것이라고 하셨는데 정말로 그렇다. 그런데 대부분의 프로그래머가 알고 있기 때문에 알고만 있는 사람과 실제로 만드는 사람의 차이가 오히려 더 크겠다는 생각이 들었다. 실천하는 사람이 되어야겠다.

• https://nomadcoders.co/community/thread/2284

  • 경험담으로 적어주신 내용이 공감 됐다. a, b와 같은 의미 없는 변수를 사용하는 코드를 본 적이 있는데 로직이 복잡하기까지 해서 골치 아팠던 기억이 난다. 반면교사로 삼고 좋은 코드를 작성해야겠다고 다짐하는 계기가 되었었다.

  • 예로 들며 첨부해 주신 링크 내용도 흥미로웠다. 매우 초보적인 실수에 해당하는 것 같은데.. 한 타가 중요한 게임에서 저런 치명적인 버그가 10년 동안 방치됐다는 게 충격적이다. 처음부터 잘 짜고, 잘 검증한 코드가 얼마나 중요한지 다시금 깨달았다.