TIL (Today I Learned)

2022.02.25

오늘 읽은 범위

4장. 주석

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

• 좋은 주석 - 정말로 좋은 주석은 주석을 달지 않을 방법을 찾아낸 주석이다.

  • 법적인 주석(저작권, 소유권 등)

  • 의도를 설명하는 주석 - 고정적인 특정 값 반환의 의도를 붙이는 것

  • 결과를 경고하는 주석 - 코드 작성자가 실수할 수 있는 내용을 붙여 경고하는 것

  • TODO 주석 - 앞으로 할 일, 당장 구현하기 어렵지만 필요한 것 들을 기록하는 것

    
    (주기적인 점검을 통해 코드의 발전 및 필요성이 없는 TODO 주석 삭제를 하자)

  • 중요성을 강조하는 주석 - 개행 하나를 추가하는 간단한 코드일지라도 중요도가 높다면 실수하지 않도록 중요성을 강조하는 주석 하나를 덧붙여 코드 문제를 방지.

• 나쁜 주석

  • 주절거리는 주석 - 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다. 독자가 이해하지 못하는 주석은 무의미

  • 오해할 여지가 있는 주석 - 주석에 정확하지 않은 정보로 인해 코드 문제가 발생하는 경우

  • 이력을 기록하는 주석 - 변경되었던 로그를 기록하는 관례인데, 과거엔 유효했으나 이제는 혼란만 야기함

  • 있으나 마나 한 주석 - 너무 당연한 사실을 언급하는 경우, 필요 없는 말, 중복

  • 위치를 표시하는 주석 - 아주 드물게 반드시 필요한 경우를 제외하고는 사용하는 것을 자제

  • 닫는 괄호에 다는 주석 - 닫는 괄호에 주석을 달아야겠다는 생각이 든다면 함수를 더 정확하고 짧게 만들도록 노력하자

  • 주석으로 처리한 코드 - 주석으로 처리된 코드는 이유가 있으리라 판단하여 지우지 않게 되고 그것이 관행이 되어 점차 쌓여나가 코드가 장황해지고 망가질 수 있다

  • 모호한 관계 - 주석이 또 다른 설명을 야기하는 경우는 없어야 한다

  • 함수 헤더 - 헤더를 붙일 바에 더 짧고, 간단하고, 한 가지만 수행하고, 이름을 잘 붙인 함수가 좋다

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

• 코드를 작성하면서 원래도 주석을 잘 사용하진 않았으나 앞으로도 정말 필요한 경우에만 사용할 수 있도록 잘 판단하고 그 내용도 정확할 수 있도록 해야겠다.

• 코드를 완성시키는 도중에 테스트를 위해서 코드를 주석 처리 하거나, 기존에 쓰던 코드를 변경하였으나 원래 코드도 언젠가 쓸 거 같아서 주석으로 해둔 경우는 몇 번 있다. 앞으로는 다른 곳에 기록을 하거나 필요 유무를 잘 판단하여 불필요한 주석들을 제거해야겠다.

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

• RFC 2045

• MSB