[TIL] 클린코드(Clean Code) - 4장. 주석

📆 TIL (Today I Learned) 날짜

2022.02.25

📚 오늘 읽은 범위

3장. 주석

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

• 나쁜 코드에 주석을 달지 마라. 새로 짜라. (p.68)
• 코드는 변화하고 진화한다. 일부가 여기서 저기로 옮겨지기도 한다. 조각이 나뉘고 갈라지고 합쳐지면서 괴물로 변한다. 불행하게도 주석이 언제나 코드를 따라가지는 않는다. 아니, 따라가지 못한다. 주석이 코드에서 분리되어 점점 더 부정확한 고아로 변하는 사례가 너무도 흔하다. (p.68)
• 부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다. 부정확한 주석은 독자를 현혹하고 오도한다. 부정확한 주석은 결코 이뤄지지 않을 기대를 심어준다. 더 이상 지킬 필요가 없는 규칙이나 지켜서는 안 되는 규칙을 명시한다. (p.69)
• 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다. 모듈을 짜고 보니 짜임새가 엉망이고 알아먹기 어렵다. 지저분한 모듈이라는 사실을 자각한다. 그래서 자신에게 이렇게 말한다. “이런! 주석을 달아야겠다!” 아니다! 코드를 정리해야 한다! (p.69)
• 주절거리는 주석 : 특별한 이유 없이 의무감으로 혹은 프로세스에서 하라고 하니까 마지못해 주석을 단다면 전적으로 시간낭비다. 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다. (p.76)
• 의무적으로 다는 주석 : 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다. 이런 주석은 코드를 복잡하게 만들며, 거짓말을 퍼뜨리고, 혼동과 무질서를 초래한다. (p.80)
• 이력을 기록하는 주석 : 예전에는 모든 모듈 첫머리에 변경 이력을 기록하고 관리하는 관례가 바람직했다. 당시에는 소스 코드 관리 시스템이 없었으니까. 하지만 이제는 혼란만 가중 할 뿐이다. 완전히 제거하는 편이 좋다. (p.80)
• 닫는 괄호에 다는 주석 : 닫는 괄호에 주석을 달아야겠다는 생각이 든다면 대신에 함수를 줄이려 시도하자. (p.85)
• HTML 주석 : 소스 코드에서 HTML 주석은 혐오 그 자체다. 다음 코드를 읽어보면 무슨 말인지 알리라. HTML 주석은 (주석을 읽기 쉬워야 하는) 편집기/IDE에서조차 읽기가 어렵다. (Javadocs와 같은) 도구로 주석을 뽑아 웹 페이지에 올릴 작정이라면 주석에 HTML 태그를 삽입해야 하는 책임은 프로그래머가 아니라 도구가 져야한다. (p.87)
• 너무 많은 정보 : 주석에다 흥미로운 역사나 관련 없는 정보를 장황하게 늘어놓지 마라. (p.88)
• 함수 헤더 : 짧은 함수는 긴 설명이 필요 없다. 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다. (p.89)

😀 오늘 읽은 소감 및 떠오르는 생각

이번 주석에 대한 내용은 사실 많이 충격적이었다. 그동안 내가 알고있었던 주석에 대한 지식들과 그동안 해왔던 행동들 대부분이 다 잘못되어 었었기 때문이다. 어디인지 기억은 잘 나지 않지만 과거 어딘가에서 코딩을 배울 때는 “주석은 최대한 많으면 좋다. 그러니 주석을 열심히 달아라!”라는 말을 강사에게 들은적이 있다. 누가 이 소스 코드를 보더라도 내용을 잘 알 수 있게 주석으로 설명을 주구절절 달아두라는식의 가르침을 받은적이 있었다. 그래서 그때부터 필요한 경우 소스 코드에다가 주석을 주구절절 다는 습관이 생기게 되었다. 근데 클린 코드 책을 읽고나니 주석으로 그런 것들을 설명할 것이 아니라 소스 코드를 잘 짜서 코드 자체로 설명이 잘 되게 만드는 것이 바람직하다는 것을 알게 됐다. 그동안 정말 무지하고 실력이 많이 부족했구나라고 느낀다.