반응형
주석을 최대한 쓰지 말자
- 주석은 나쁜 코드를 보완하지 못한다.
- 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
// 직원에게 복지 혜택을 받을 자격이 있는지 검사
if ((employee.flags & HOURLY_FLAG) && employee.age > 65)
if (employee.isElligibleForFullBenefits())코드로도 좋은 의도를 표현할 수 있다.
주석은 방치된다. 새로운 추가 기능 및 변경사항이 생기면 주석도 수정을 해야한다.
코드는 컴파일되어 호출되지만, 주석은 그저 주석이기 때문에 결국 의미없는 텍스트가 되어버린다.
좋은 주석
// kk:mm:ss EEE, MMM dd, yyyy 형식
Pattern timeFormat = Pattern.compile("\\d*:\\d:\\d* \\w*, \\w* \\d* \\d*")
// 스레드를 많이 생성하여 시스템에 영향을 끼쳐 테스트를 만들도록 함
for (int i = 0; i < 25000; i++){
SomeThread someThread = ThreadBuilder.builder().build();
}
// 유저로부터 입력받을 값을 저장할 때 trim으로 공백제거 필요
String username = userNameInput.trim();구현에 대한 정보를 제공하거나, 의도와 중요성을 설명하는 주석은 좋은 주석으로 볼 수 있다.
TODO, FIXME 주석
- TODO : 앞으로 할일. 지금은 해결하지 않지만 나중에 해야할 일을 미리 적어둘 때
- FIXME : 문제가 있지만, 당장 수정할 필요는 없을 때. 가능한 빨리 수정하는 것이 좋다.
IDE에서 하이라이팅이 되고, 별도의 윈도우에서 볼 수 있다.
주석보다 annotation
- ANNOTATION : 코드에 대한 메타 데이터
- 코드의 실행 흐름에 간섭을 주기도 하고, 주석처럼 코드에 대한 정보를 줄 수 있다.
- @Deprecated : 컴파일러가 warning을 발생시킴. IDE에서 사용시 표시됨
- @NotThreadSafe : Thread Safe하지 않음을 나타냄
JavaDoc
- JAVA 코드에서 API 문서를 HTML 형식으로 생성해주는 도구
- /** */ 과 같이 *2개를 사용하여 사용한다.
CLASS LEVEL
@link를 통해 JavaDoc 에서 클래스로 링킹이 된다.
FIELD LEVEL
METHOD LEVEL
p 태그, a태그들이 보인다. param, return 등에 대한 설명이 들어가 있다.
Javadoc 문서
보통 외부에 코드를 공유할 일이 생겼을 때 javadoc 을 사용해서 가독성을 높여주는 경우도 있다.
좋은 주석도 있지만, 가독성이 좋은 코드를 사용하는 것을 최우선으로 하자.
본 포스팅은 Clean Code (Robert C. Martin), 제로베이스-한달한권(클린코드)를 참고하여 작성하였습니다.
반응형
