명확하고 간결한 주석 달기

주석은 명확하게 최대한 구체적이고 자세하게 작성해야 한다.
주석은 높은 '정보 대 공간' 비율을 갖춰야 한다.

• 주석을 간결하게 해라
  한줄로 할 수 있는것을 여러줄로 나누어 표기하지 말것.

• 모호한 대명사는 피해라
  it, this 가 가리키는 것이 무엇인지 명확하게 그리고 이런 모호한 대명사보다는 명확한 명사로 바꾸어 주는 것이 혼동이 덜 할것이다.

• 엉터리 문장을 다듬어라
  주저리주저리 같은 말이지만 문장의 길이가 길어진 것에 대해 조금 더 생각해보고 더 나은 문장으로 다시 다듬어 주석을 만들어야 한다. 그래야 간단하고 짧고 직접적이다.

• 함수의 동작을 명확하게 설명해라
  단순하게 반환한다라는 주석 말고 어떻게 무엇을 반환하는지 설명을 해주는 것도 좋은 주석이다.

• 코너케이스를 설명해주는 입/출력 예를 사용해라
  이슈가 발생할만한 그런 궁금증을 해소시켜줄 수 있는 그러면서 동시에 어떻게 동작하는지에 대한 주석을 달아주게 되면 깔끔하게 읽을 수 있는 좋은 주석을 완성 시킬 수 있을 것이다.

• 코드의 의도를 명시하라
  당연하게 누군가가 봐도 알 수있는 코드의 정확한 기능은 주석으로 하지 말고, 프로그램의 의도를 설명해주는 주석을 다는 습관을 들여야한다.

• 이름을 가진 함수 파라미터 주석
  파이썬의 예로, 함수의 매개변수 인자 앞에 주석처리를 하여 어떤 매개변수가 들어가게 되는지 설명할 수있는 표현을 넣어주는 주석도 좋은 방법이다.

• 정보 축약형 단어를 사용하라
  내가 뭔가를 적을때 이렇게 길게 쓴 주석이 많은 것 같은데 길게 늘어지는 주석을 써야한다면 대표젹인 예를 들던지 또는 요약해서 던져줄 수 있는 그런 주석을 기재해야 한다.

요약정리

• it이나 this 같은 대명사가 여러 가지를 가리킬 수 있다면 사용하지 않는 것이 좋다.
• 함수의 동작을 실제로 할 수 있는 한도 내에서 최대한 명확하게 설명해라.
• 신중하게 선택된 입/출력 예로 주석을 서술해라.
• 코드가 가진 의도를 너무 자세한 내용이 아니라 높은 수준에서 개괄적으로 설명해라.
• 같은 줄에 있는 주석으로 의미가 불분명한 함수의 인수를 설명해라.
• 많은 의미를 함축하는 단어로 주석을 간단하게 만들어라.

여기까지가 요약이다. 이 6장까지는 많은 위험이나 노력을 들이지 않고 코드를 한줄씩 수정해 나가면서 코드의 가독성을 높이는 표면적 개선을 알아봤다.

여기까지만 봐도 내가 작성한 코드들이 살짝씩 떠오르면서 아! 이럴때는 이런식으로 했어야 됐구나 하면서 그리고 지금 진행하는 프로젝트에도 조금씩 적용해 넣어보려고 노력중이다.

이 책이 내 코드 가독성을 한층 높여주는 것 같아서 너무 좋게 읽고있다. 이상으로 포스팅을 마치겠다.