나쁜 코드에 주석을 달지 마라. 새로 짜라.
코드로 의도를 표현하지 못한, 즉 실패한 코드에 다는 것이 주석이다. 주석이 필요한 상황에 처하면 코드를 변경할 수 없을지를 고민해라.
- 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
좋은 주석
-
법적인 주석
저작권 정보와 소유권 정보 -
정보를 제공하는 주석
// kk:mm:ss EEE, MMM dd, yyyy 형식이다 같은 -
의도를 설명하는 주석
개인적으로는 가장 유용하다고 생각함 -
의미를 명료하게 밝히는 주석
assertTrue(a.compareTo(a) == 0); // a == a -
결과를 경고하는 주석
// 대륙간탄도미사일을 발사하는 코드, 전쟁을 원할 때만 실행하시오 -
TODO주석
VSCode에서 아주 유용하다 -
중요성을 강조하는 주석
-
공개 API에서 Javadocs -> Dart는 DartDoc
DartDoc에서는 ///로 주석을 단다
나쁜 주석
예시가 필요한가? 좋은 주석을 제외하면 모조리 나쁜 주석이다
그래도 예시를 한다면
- 같은 말 중복
- 주저리주저리
- 알고리즘을 설명하는 주석
- 오해할 여지가 있는 주석
- 의무적으로 다는 주석 (칸 채우기?)
- 변경 이력을 기록 하는 주석 : 그냥 Git을 써라
- 저자를 표시하는 주석 : Git을 쓰라고
- 주석으로 처리한 코드 : Git을 쓰라니깐
그외 옛 선조들의 나쁜 습관들을 많이 예시를 해놓았지만 지금은 2024년이라 주석도 많이 깔끔해진 편이다.
위 사항들만 주의하자.
// 주석은 코드와 따로 관리를 해줘야하기 때문에 코드처럼 명확히 관리할 것이 아니면 줄이거나 쓰지 않는 것이 옳다.
클린코드를 함께 읽고 있는 나의 최애 북TIL 3명
디테일의 정석
https://daehun.notion.site/TIL-4-of-22-3-e5d179d1ced94108a6d78d11762b397e심플한 요약
https://velog.io/@ttungnyang2/%ED%81%B4%EB%A6%B0%EC%BD%94%EB%93%9C-DAY-04색다른 발상과 주관의 정리
https://velog.io/@wonjang/%ED%81%B4%EB%A6%B0%EC%BD%94%EB%93%9C-%EB%A7%A4%EC%9D%BC-%EC%9D%BD%EA%B8%B0-TIL-4%EC%9E%A5.-%EC%A3%BC%EC%84%9D
