4. 주석

주석은 기껏해야 필요 악이나. 주석은 너무 자주 거짓말을 하기 때문이다 (코드와 동떨어지기 쉬워서) 부정확한 주석은 아에 없는 주석보다 훨씬 더 나쁘며, 진실은 코드에만 존재한다.

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

표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.

코드로 의도를 표현하라

주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다

좋은 주석

• 법적인 주석: 법적인 이유로 특정 주석을 명시해야 하는 경우
• 정보를 제공하는 주석: 기본적인 정보 제공
• 의도를 설명하는 주석: 결정에 깔린 의도까지 설명하는 주석
• 의미를 명료하게 밝히는 주석
• 결과를 경고하는 주석
• TODO 주석
• 중요성을 강조하는 주석: 자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위한 주석

나쁜주석

• 주절거리는 주석: 주석을 이해하기 위해 다른 모듈까지 파해쳐 봐야 하는 주석은 바이트만 낭비할 뿐이다
• 같은 이야기를 중복하는 주석
• 오해할 여지가 있는 주석
• 의무적으로 다는 주석
• 있으나 마나 한 주석: 너무 당연한 사실 언급하거나 새로운 정보 제공하지 못하는 주석
• 함수나 변수로 표현할 수 있다면 주석을 달지 마라
• 위치를 표현하는 주석: 반드시 필요할때만 아주 드물게 사용해라
• 주석으로 처리한 코드: 주석으로 처리한 코드만큼 밉살스러운 관행도 드물다. (소스코드 관리 시스템이 코드를 기억해주니 안심하고 삭제고고)
• HTML 주석
• 전역 정보: 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라
• 너무 많은 정보: 주석에다 쓸때없는 정보 장황하게 늘어놓치 말아라
• 모호한 관계: 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다
• 함수 헤더

다른 사람의 TIL

• https://velog.io/@lucki/%EB%85%B8%EA%B0%9C%EB%B6%81-%ED%81%B4%EB%A6%B0%EC%BD%94%EB%93%9C-TIL-4%EC%9E%A5.-%EC%A3%BC%EC%84%9D
• https://ujaa.tistory.com/11
• https://caring-tick-99e.notion.site/3-6ed2330b406b4c49a4a4d29ef5dac23d

#노개북 #노마드코더 #개발자북클럽