오늘 TIL 3줄 요약

- 주석을 사용하는것 보다, 코드를 깔끔하게 정리하고 표현력을 강화하는 방향이 더 낫다.
- 좋은 주석은 없다. 좋은 주석을 생각하는것 보단 코드로 표현하는 편이 훨씬 낫다.

TIL (Today I Learned) 날짜

2022.04.28-29

오늘 읽은 범위

4장 주석

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

우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다. 주석 없이는 자신을 표현할 방법을 찾지 못해 할 수 없이 주석을 사용한다. 그러므로 주석이 필요한 상황에 처하면 곰곰이 생각하기 바란다.

코드는 변화하고 진화한다. 일부가 여기서 저기로 옮겨지기도 한다. 불행하게도 주석이 언제나 코드를 따라가지는 않는다. 따라가지 못한다. 필자라면 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로, 그래서 애초에 주석이 필요 없는 방향으로 에너지를 쏟겠다.

• 주석은 나쁜 코드를 보완하지 못한다.

  코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다. “이런! 주석을 달아야겠다!” 가 아니라 코드를 정리해야 한다!

• 코드로 의도를 표현하라

  //직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
  if((employee.flags & HOURLY_FLAG)&& (employee.age > 65)
  

  위의 예제와 아래예제 어느쪽이 더 나은가?

  if(employee.isEligibleForFullBenefits()) 
  

• 좋은 주석

  어떤 주석은 필요하거나 유익하다. 물론 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라는 사실!

  • 법적인 주석

    예를 들어, 각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보는 필요하고도 타당하다

  • 정보를 제공하는 주석

    예를 들어, 코드에서 사용한 정규표현식이 시각과 날짜를 뜻한다는 설명(이왕이면 시각과 날짜를 변환하는 클래스를 만들어 코드를 옮겨주면 더 좋고 더 깔끔하겠다)

  • 의도를 설명하는 주석

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

    일반적으로 인수나 반환값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워진다. 물론 그릇된 주석을 달아놓을 위험은 상당히 높다. 더 나은 방법이 없는지 고민하고 정확히 달도록 각별히 주의한다.

  • 결과를 경고하는 주석

  • TODO 주석

    앞으로 할 일을 주석으로 남겨두면 편하다. 하지만 TODO로 떡칠한 코드는 바람직하지 않다. 주기적으로 TODO 주석을 점검해 없애도 괜찮은 주석은 없애라

  • 중요성을 강조하는 주석

    대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서도 주석을 사용한다.

  • 공개 API에서 Javadocs

    설명이 잘 된 공개 API는 참으로 유용하고 만족스럽다.

• 나쁜주석

  • 주절거리는 주석

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

  • 오해할 여지가 있는 주석

  • 의무적으로 다는 주석

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

  • 이력을 기록하는 주석

  • 있으나 마나 한 주석

  • 무서운 잡음

    때로는 Javadocs도 잡음이다. 아래와 같은

    /** The name **/
    private String name;
    

  • 함수나 변수로 표현할 수 있다면 주석을 달지 마라

  • 위치를 표시하는 주석

  • 닫는 괄호에 다는 주석

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

  • 주석으로 처리한 코드

  • HTML 주석

  • 전역정보

  • 너무 많은 정보

  • 모호한 관계

    주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다. 적어도 독자가 무슨소린지 알아야 하지 않나

  • 함수 헤더

  • 비공개 코드에서 Javadocs

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

주석이 많이 달린 코드를 봤을 때, 먼저 친절하단 생각을 했었던것 같다. 그리고 그 주석이 틀릴거라는 생각을 안했던 것 같다. 작업하면서 주석이 필요할것 같은데? 라는 생각이 들 때가 있었는데..그 때 난 나쁜 코드를 짜고 있었나 보다. 주석대신 코드로 최대한 표현을 해야한다는 말이 이번 장에서만 강조하는게 아닌걸 보니, 어떻게 짜면 코드에 모든 나의 의도를 깔끔하게 잘 표현할 수 있을지 계속 고민해 봐야겠다.

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

주석으로 인해 겪었던 다른 개발자의 이야기를 찾아봐야겠다.

오늘 읽은 다른사람의 TIL