TIL (Today I Learned)

// 2022.02.25

오늘 읽은 범위

// 4장. 주석

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

• 나쁜 코드에 주석을 달지 마라. 새로 짜라

   

  잘 달린 주석은 그 어떤 정보보다 유용하다. 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다. 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다.

   

  주석은 언제나 실패를 의미한다.

   

   

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

  • 코드로 의도를 표현하라

    • 코드만으로 의도를 설명하기 어려운 경우가 존재한다.

    • 많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.

  • 좋은 주석

    • 법적인 주석

    • 정보를 제공하는 주석

    • 의도를 설명하는 주석

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

    • 결과를 경고하는 주석

    • TODO 주석

    • 중요성을 강조하는 주석

    • 공개 API에서 Javadocs

  • 나쁜 주석

    • 주절거리는 주석

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

    • 오해할 여지가 있는 주석

    • 의무적으로 다는 주석

    • 이력일 기록하는 주석

    • 있으나 마나 한 주석

    • 무서운 잡음

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

    • 위치를 표시하는 주석

    • 닫는 괄호에 다는 주석

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

    • 주석으로 처리한 코드

    • HTML 주석

    • 전역 정보

    • 너무 많은 정보

    • 모호한 관계

    • 함수 헤더

    • 비공개 코드에서 Javadocs

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

생각해보면 주석을 달았던 상황을 보면 작성한 코드론 설명이 부족했어였다. 필요하지 않으면 주석은 최대한 지양하고 코드를 직관적으로 깔끔하게 작성할 수 있도록 해야겠다.

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