첫페이지부터 글쓴이는 강하게 이야기했다.
주석은 순수하게 선하지 못하다. 주석은 필요악이다.
이전에 자주 함수의 기능을 설명하기 위해 주석을 달곤했는데, 클린코드는 정말 많은 가르침을 주는거같다.
- 주석은 필요악이다
- 주석이 필요한 상황에 처하면 코드로 의도를 표현할 방법을 찾자
- 주석은 나쁜 코드를 보완하지 못한다.
- 주석으로 달려는 설명을 함수로 만들어 표현하자
- 좋은 주석이란?
- 법적
- 저작권 정보나 소유권 정보
- 정보 제공
- 이것도 웬만하면 코드로 설명하기
- 정규표현식이 무슨뜻인지 설명할때 정도는 사용해도되지만, 정규표현식을 사용하여 데이터를 처리하는 클래스를 만들어서 그쪽으로 코드를 옮긴다면 더 깔끔하다.
-
//kk:mm:ss EEE, MMM dd, yyyy 형식이다. Pateern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d, \\d");
-
- 의도 설명
- 코드를 이처럼 구현하게된, 결정에 깔린 의도를 설명하는 용도
- 두 객체를 비교할때 왜 이 객체를 더 우선순위를 높게 매기도록 결정했는지 주석으로 써놓는경우
- 의미를 명료하게 밝히는것
- 일단은 모호한 인수나 반환값은 의미가 드러나게끔 코드로 표현하는게 더 좋지만
- 만약 표준 라이브러리라서, 같은 경우로 변경을 못한다면 주석으로 의미를 명료하게 밝히자
-
assertTrue(a.compareTo(a) == 0 ); //a == a
- 결과를 경고하는 것
- 예를들어, 특정 테스트케이스는 웬만하면 돌리지 말아야할때, 경고하는것
- 오래 걸린다든가, 서버에 부담이 좀 된다든가 등등
- 예를들어, 특정 테스트케이스는 웬만하면 돌리지 말아야할때, 경고하는것
- TODO
- 앞으로 할일을 todo주석으로 남기는거
- 이거 해봤는데 자바에서 있는거고, 이주석은 네온색이됨
- 중요성을 강조하는 주석
- 자칫 넘어갈만한 뭔가를 강조하기 위한거
- 이 코드가 꼭 있어야 이게 된다던지 그런것
- 공개API > Javadocs
- 법적
- 나쁜 주석이란?
- 주절거리는것
- 중복적인것
- 오해할만한 것
- 의무적으로 다는것
- 이력을 기록하는것
- 필요없는 것
- 잡음
- 함수나 변수로 표현가능하다면 달지말기
- 닫는 괄호에 다는 주석
- 저자를 표시하는 주석
- 주석으로 처리한 코드
- HTML 주석
- 전역 정보
- 너무 많은 정보
- 모호한 관계
- 함수 헤더
- 비공개 코드의 Javadocs
정리하고 나니 나쁜주석에 대한 설명이 훨씬 많음을 알 수 있었다.
주석을 써야할때와 쓰지말아야할때를 정확하게 학습해서 사용해야겠다.
'클린코드' 카테고리의 다른 글
[클린코드 독서] 5장 - 형식 맞추기 (0) | 2022.03.09 |
---|---|
[클린코드 독서] 6장 - 객체와 자료구조 (0) | 2022.02.20 |
[클린코드 독서] 3장 - 함수 (0) | 2022.01.30 |
[클린코드 독서] 2장 - 의미 있는 이름 (0) | 2022.01.23 |
[클린코드 독서] 1장 - 깨끗한 코드 (0) | 2022.01.23 |