[클린 코드] Assignment #05: TIL - 4장. 주석 + 나의 최애 북틸

 

📢 DAY 6~7
🏷️ 오늘 읽은 범위: 4장. 주석

🖊️ 짧은 내용 요약

• 주석은 꼭 필요한 상황이 아니라면 쓰지 않는 게 제일 좋다.
•  왜냐하면 주석은 좋은 주석보다 나쁜 주석이 더 많기 때문이다.
• 다음의 나쁜 주석의 특징 및 유형이다.
  • 작성한 사람만 아는 주석(추가 설명을 요하는 주석)
  • 코드와 중복된 내용이 있는 주석(의무적으로 달린 주석)
  • 오해의 여지가 있는 내용이 담긴 주석
  • 가독성을 방해하는 주석(닫는 괄호에 적힌 주석)
  • 기타 쓸데없는 주석(이력, 분풀이 주석, 실수, 작성한 사람, 주석 코드, 다른 위치에 있는 코드를 설명, 너무 많은 정보)
• 나쁜 주석이 생기는 이유는 크게 3가지다.
  1. 주석은 유지보수하기 어렵다. 그래서 시간이 지나면 주석이 쓸데없는 정보로 변한다.
  2. 프로그래머가 정확한 의도로 주석을 달지 못 할 수도 있다.
  3. 코드 품질이 나빠 설명하는데 주석을 추가한다.
• 나쁜 주석은 다음과 같은 영향을 미친다.
  1. 코드이 가독성을 떨어트려 코드를 이해하는데 더 많은 시간이 소요된다.
  2. 코드를 대충 읽고 넘어가게 만든다.
• 그렇기 때문에 주석을 달기 보단 코드로 모든 의도를 표현하는 게 좋다.
• 하지만 물론 작성하면 좋은 주석도 있다. 좋은 주석은 코드를 작성한 의도나 근거를 설명해서 코드를 정당화하거나,  코드보다 더 많은 정보를 제공한다. 주석이 코드보다 제공할 수 있는 더 많은 정보의 예시로는 저작권 정보와 소유권 정보와 같은 법적인 정보, 코드 실행의 결과를 경고하거나, 코드 상에서 중요한 점을 강조한 부분이 있다.
• 결론적으로 주석은 이후에 코드를 읽는 사람이 코드를 이해하는데 도움이 되는가를 생각하면서 작성하면 된다.

😀 책에서 기억하고 싶은 내용

잘 달린 주석은 그 어떤 정보보다 유용하다.
경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다.
오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼트려 해악을 미친다. (p. 68)

잘 달린 주석은 그 어떤 정보보다 유용하다. 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다. 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼트려 해악을 미친다. (p. 68)

TODO 주석은 프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무를 기술한다. ... 하지만 어떤 용도로 사용하든 시스템에 나쁜 코드를 남겨 놓는 핑계가 되어서는 안 된다. (p. 74 ~ 75)

모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다. 이런 주석은 코드를 복잡하게 만들며, 거짓말을 퍼뜨리고, 혼동과 무질서를 초래한다. (p. 80)

주석을 다는 목적은 코드만으로 설명이 부족해서다. 주석 자체가 다시 설명을 요구하니 안타깝기 그지없다. (p. 89)

🤔 오늘 읽은 소감 & 떠오르는 생각

이번 챕터를 읽으면서 주석은 시간이 지날수록 나쁜 주석이 되기 쉽다는 사실을 처음 알게 되었다. 아무래도 저자처럼 많은 코드를 읽은 사람은 주석을 유지보수하기 힘들다는 사실을 알게 되나 보다. 그리고 내용을 읽으면서 의무적으로 달린 주석의 예시로 모든 함수에 javadocs를 넣은 예시를 봤다. 나도 예전에 이렇게 작성하는 코드가 잘 정돈된 코드라고 생각했고, 함수의 파라미터를 쉽게 파악할 수 있게 도와준다고 생각해 작성했었다. 그래서 처음에는 왜 이 내용이 나쁜 주석의 예시로 들어가 있는지 이해가지 않았다. 근데 뒤에 영어로 작성된 주석 예시를 보니까 영어로 파라미터를 쓰고, 영어로 주석을 동일하게 작성하면 내용이 많이 겹치는 것을 보면서 파라미터를 설명하는 javadocs가 왜 의미없는 주석인지 알게 되었다. 영어로 주석을 쓰는 경우와 한글로 주석을 쓰는 경우에 다가오는 느낌이 다른 것 같다. 코딩을 아무래도 영어로 하다보니 한글로 주석을 쓰면 주석이 해석처럼 쓰여 조금 더 쓸모있게 느껴졌던 것 같다.

🔍 새로 알았거나 잘 이해되지 않는 내용

• Javadocs
  코드를 유지보수하기 위해 사용하는 자바용 문서화 툴

💘 나의 최애 북틸

1. kitty3365님의 [TIL] 3장. 함수
   나는 책에서 함수의 인수 부분을 읽으면서 인수는 최대한 무조건 0개로 하자..! 라고 생각했는데 kitty3365님은 상황에 따라 다른 것 아니냐는 유연한 사고을 보여주셔서 멋있어서 선정했다.
2. h1335 님의 [TIL] 3장. 함수
   생각을 너무 잘 정리하셔서 내용이 술술 읽혔다. h1335님의 다짐도 잘 보이고 나도 같이 동기부여 받는 느낌이 들어 선정했다.
3. 원장님의 [ 클린코드 매일 읽기 ] TIL 3장. 함수
   소감 부분에서 자신이 이해한 내용을 확인하기 위해 예시를 작성하신 것이 도움이 되었다. 이렇게 작성하면 보는 사람도 이해가 잘 되고, 자신도 정확히 이해할 수 있어서 1석2조의 이득이 있는 것 같아 선정했다.

나는 책을 읽으면서 비판적 사고를 잘 못하는 편인데, 다른 사람들은 책을 읽으면서 본인의 생각 기준에 맞게 내용을 받아들이는 모습을 보면서 배워야겠다는 생각이 들었다. 그리고 다른 사람들의 TIL를 읽으면서 놓쳤던 내용도 다시 인지하고, 책이 말하고자 하는 큰 내용을 파악하는데 도움이 되었다.

📚 참고

• https://breakcoding.tistory.com/385