반응형
3. 주석
- 저자는 주석에 대해 Clean Code를 코드로만 달성하는 것이 실패해서 넣는 것을 주석이라고 말한다.
- 특히 그는 주석은 오래될 수록 실제 돌아가는 코드와 멀어지게 되며 프로그래머들이 주석까지 다 유지보수를 하기엔 쉽지 않다고 말하고 있다.
- 주석은 애시당초 처음부터 나쁜 코드는 보완하지 못 한다.
- 코드로 의도를 표현해야 한다.
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65)) {
...
}
if (employee.isEligibleForFullBenefits()) {
...
}
처음부터 주석으로 설명해야만 하는 코드가 아닌 후자처럼 주석이 필요없는 코드가 이상적이다.
- 그나마 좋은 주석의 조건은 아래라고 필자는 말한다. (동시에 그래도 없는게 제일 낫다고 함)
- 정보를 제공하는 주석
- 예를 들면 추상 메서드가 반환할 값을 설명한다든가, 정규 표현식에 대한 설명을 한번에 볼 수 있게 써 놓는 것이 있다.
- 의도를 설명하는 주석
- 왜 이렇게 개발을 했었는지에 대한 결정에 깔린 의도까지 설명하는 주석은 가치가 있다.
- 결과를 경고하는 주석
- 다른 개발자에게 결과를 경고할 목적으로 주석을 사용할 수 있다.
- 예를 들면 특정 테스트 코드에 대해서는 소요시간이 오래 걸리니 실행할 때 조심해라는 주석을 달 수 있다.
- TODO 주석
- 정보를 제공하는 주석
- 아래의 주석들은 오히려 달지 않는 것이 좋은 주석이다.
- 의무적으로 다는 주석
- 전회사에서도 했던 건데 @param title ~~ @param 이런 식으로 하는 것
- 이건 변수명만 봐도 알 수 있게 코드를 작성했어햐 했다.
- 이력을 다는 주석
- //기본 생성자 // 월 중 일자를 반환한다. 와 같은 안 봐도 알 수 있는 함수의 주석
- 닫는 괄호에 다는 주석
- 이는 함수가 복잡할 때 보통 다는데 '여기 닫는 괄호는 while의 괄호고 여기 닫는 괄호는 if의 괄호이다' 이런식으로 이거 자체가 clean code에서 멀어져있으니 추상화를 낮춰 쪼갠다.
- 누가 개발했는지 쓰지 마라
- 코드를 주석처리 해놓지 마라
- 이건 후에 제3자가 보면 지우기 주저하게 만든다.
- 전역 정보에 대한 주석
- 의무적으로 다는 주석
반응형
'개발 일반' 카테고리의 다른 글
개발 일반잊을 때쯤 한번 다시 읽어봐야할 Clean code에 관하여 (경계) (0) | 2021.03.23 |
---|---|
개발 일반잊을 때쯤 한번 다시 읽어봐야할 Clean code에 관하여 (오류 처리) (0) | 2021.03.23 |
잊을 때쯤 한번 다시 읽어봐야할 Clean code에 관하여 (함수) (0) | 2021.03.15 |
잊을 때쯤 한번 다시 읽어봐야할 Clean code에 관하여 (의미 있는 이름) (0) | 2021.03.15 |
잊을 때쯤 한번 다시 읽어봐야할 Clean code에 관하여 (들어가며) (0) | 2021.03.15 |