노션에서 정리한 내용을 벨로그로 옮겼기 때문에 노션으로 보면 조금 더 보기 더 편합니다🤗
이동하기 → junnkk's Notion
주석을 줄이도록 노력하자
주석은 나쁜 코드를 보완하지 못한다
주석을 추가하는 이유 : 코드 품질이 나빠서
- 표현력이 풍부하고 깔끔하고 주석이 없는 코드는 복잡하고 어수선하고 주석이 많이 달린 코드보다 좋다
코드로 의도를 표현하라!
좋은 주석
-
법적인 주석
-
정보를 제공하는 주석
-
의도를 설명하는 주석
결정에 깔린 의도 설명 ex) 두 객체를 비교할 때다른 어떤 객체보다 자기 객체에 높은 순위를 주기로 결정
-
의미를 명료하게 밝히는 주석
인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석 유용
-
결과를 경고하는 주석
-
TODO 주석
앞으로의 할일. 주기적으로 점검해서 삭제 =
-
중요성을 강조하는 주석
-
공개 API에서 Javadocs
나쁜 주석
-
주절거리는 주석
특별한 이유 없이 다는 주석은 시간 낭비
-
같은 이야기를 중복하는 주석
코드 내용을 그대로 중복한 주석은 사용 X
-
오해할 여지가 있는 주석
-
의무적으로 다는 주석
-
이력을 기록하는 주석
현재에는 소스 코드 관리 시스템이 있으므로 사용 X
-
있으나 마나 한 주석
너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석 사용 X
-
무서운 잡음
때로는 Javadocs도 잡음.
-
함수나 변수로 표현할 수 있다면 주석을 달지 마라
-
위치를 표시하는 주석
-
닫는 괄호에 다는 주석
-
공로를 돌리거나 저자를 표하는 주석
-
주석으로 처리한 코드
-
HRML 주석
-
전역 정보
주석을 달어야 한다면 근처에 있는 코드만 기술하라.
코드 일부에 주석을 달면서시스템의 전반적인 정보를 기술하지 마라.
-
너무 많은 정보
-
모호한 관계
-
함수 헤더
짧은 함수는 긴 설명이 필요 X
-
비공개 코드에서 Javadocs
공개 API는 Javadocs가 유용하지만 공개하지 않을 코드라면 쓸모 X
시스템 내부에 속한 클래스와 함수에 Javadocs를 생성할 필요 X
-
예제
→ 5장 형식 맞추기
