노개북 클린코드(clean code) 2022.02.24~25

오늘 읽은 범위

4장 주석

 

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

• 잘 달린 주석은 그 어떤 정보보다 유용하다. 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다. 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다. -> 이번 장의 내용을 한마디로 말해주는 구문이라고 생각한다.
• 코드만이 자기가 하는 일을 진실되게 말한다. 코드만이 정확한 정보를 제공하는 유일한 출처다.
• 좋은 주석
  • 법적인 주석
  • 정보를 제공하는 주석
  • 의도를 설명하는 주석
  • 의미를 명료하게 밝히는 주석
  • 결과를 경고하는 주석
  • TODO 주석
  • 중요성을 강조하는 주석
• 나쁜 주석
  • 주절거리는 주석 : 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다.
  • 같은 이야기를 중복하는 주석
  • 오해할 여지가 있는 주석
  • 의무적으로 다는 주석
  • 이력을 기록하는 주석 -> git 을 활용하면 좋다.
  • 있으나 마나 한 주석
  • 무서운 잡음 : 함수나 변수로 표현할 수 있다면 주석을 달지 마라
  • 위치를 표시하는 주석
  • 닫는 괄호에 다는 주석
  • 공로를 돌리거나 저자를 표시하느 ㄴ주석
  • 주석으로 처리한 코드
  • HTML 주석
  • 전역 정보 : 주석을 달아야 한다면 근처에 있는 코드만 기술하라
  • 너무 많은 정보 : 주석에 흥미로운 역사나 관련 없는 정보를 장황하게 늘어놓지 마라
  • 모호한 관계 : 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다. 
  • 함수 헤더

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

어제 오늘 범위였던 주석 또한 함수처럼 과거의 나를 돌아보게 했다. 신입으로 입사한 첫 회사에서 내가 작성한 코드에 자신이 없어 구구절절 편지를 쓰듯 주석을 달았었다. 구구절절. 그 땐 주석을 한줄 한줄 달아두는게 나에게도 동료들에게도 좋은 일이라고 생각했다. 주석을 열심히 다는 나 = 열심히 일하는 나 라는 말도 안되는 공식이 머리에 박혀있었다. 

하지만 일주일만에 코드를 다시 열어보면 주석을 봐도 이해가 안될 때가 있었다. 그때그때 생각나는대로 함수명과 변수명을 정하고 의식의 흐름대로 주석을 달아놓으니 시간이 조금만 흘러도 코드를 이해하는 것이 어려워졌다. 

지금은 주석을 예전처럼 많이 작성하지는 않지만 여태 내가 달았던 주석들을 돌이켜 보면 TODO를 제외하면 나쁜 주석의 범주에 들어가는 것 같다. 물론 TODO 도 작성만 해두고 그 후 관리를 하지 않아 주렁주렁 남아있지만...

 

지금은 아니지만 이전 회사에선 업무상 공유를 해야했던 내용도 주석으로 적어 기록을 남겼던 것 같다. 돌이켜보면 팀 위키문서를 만들어 관리를 했어야 하지만 당시 회사 분위기는 주석 관리는 커녕 커밋 메시지 작성 방법도 정립되어있지 않아 되는대로 개발했었다. 

 

책을 읽고 TIL을 작성하며 생각해보니 오늘 작업한 코드에도 주석을 달았다. 수정해야겠다.

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

• 오전에 슬랙에 어떤 분께서 질문 주신 것처럼 영어를 모국어로 사용하지 않는 작업자들이 달아두는 주석에 대해 생각을 해봐야할 것 같다.