클린코드 핵심 정리 (4장 주석)
주석을 최대한 쓰지 말자
주석은 나쁜 코드를 보완하지 못한다.
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && employee.age > 65))
// ==> 복지 혜택에 연금 혜택 기준이 추가된다면?
// 의미있는 이름을 지으면 해결된다.
if (employee.isEligibleFourFullBenefits())
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && employee.age > 65))
// ==> 복지 혜택에 연금 혜택 기준이 추가된다면?
// 의미있는 이름을 지으면 해결된다.
if (employee.isEligibleFourFullBenefits())
코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
자신이 저지른 난장판을 주석으로 설명하지 말고 개선하는데 시간을 보내야 한다.
코드로도 의도를 표현할 수 있다!
주석은 방치된다.
코드의 변화에 따라가지 못하고, 주석은 방치된다.
코드는 컴파일되어 호출되지만, 주석은 그저 주석이기 때문에 그 자리에 방치되고 결국 의미없는 텍스트가 되어버린다.
좋은 주석
// kk:mm:ss EEE, MMM dd, yyyy 형식
Pattern timeFormat =
Pattern.compile("\\d*:\\d:\\d* \\w*, \\w* \\d* \\d*");
// kk:mm:ss EEE, MMM dd, yyyy 형식
Pattern timeFormat =
Pattern.compile("\\d*:\\d:\\d* \\w*, \\w* \\d* \\d*");
구현에 대한 정보를 제공한다.
// 스레드를 많이 생성하여 시스템에 영향을 끼쳐 테스트를 만들도록 함
for (int i = 0; i < 15000; i++) {
SomeThread someThread = ThreadBuilder.builder().build();
}
// 유저로부터 입력받을 값을 저장할 때 trim으로 공백제거 필요
String userName = userNameInput.trim();
의도와 중요성을 설명한다.
//TODO
//FIXME
TODO
: 앞으로 할 일. 지금은 해결하지 않지만 나중에 해야할 일을 미리 적어둘 때.FIXME
: 문제가 있지만, 당장 수정할 필요는 없을 때. 가능하면 빨리 수정하는게 좋다.
IDE에서 하이라이팅되고, 별도의 윈도우에서 볼 수 있다.
주석보다 annotation
java.lang.annotation
annotation = 코드에 대한 메타 데이터
- 코드의 실행 흐름에 간섭을 주기도 하고, 주석처럼 코드에 대한 정보를 줄 수 있다.
@Deprecated: 컴파일러가 warning을 발생시킴. IDE에서 사용시 표시됨
@NotThreadSafe: Thread Safe하지 않음을 나타냄.
JavaDoc
Java 코드에서 API 문서를 HTML 형식으로 생성해주는 도구
// This is a single line comment
/*
* This is a regular multi-line comment
*/
/**
* This is a Javadoc
*/
Class level
/**
* Hero is the main entity we'll be using to ...
*
* Please see the {@link com.baeldung.javadoc.Person} class for true identity
* @author Captain America
*/
public class SuperHero extends Person {
// fileds and methods
}
Field level
/**
* The public name of a hero that is common knowledge
*/
private String heroName;
Method level
/**
* <p>This is a simple description of the method ...
* <a href="http://www.supermanisthegreatest.com">Superman!</a>
* </p>
* @param incomingDamage the amount of incoming damage
* @return the amount of health hero has after attack
* @see <a href="Http://www.link_to_jira/HERO-402">HERO-402</a>
* @since 1.0
*/
public int successfullyAttacked(int incomingDamage) {
// do something
return 0;
}
Javadoc 문서
// This is a single line comment
/*
* This is a regular multi-line comment
*/
/**
* This is a Javadoc
*/
/**
* Hero is the main entity we'll be using to ...
*
* Please see the {@link com.baeldung.javadoc.Person} class for true identity
* @author Captain America
*/
public class SuperHero extends Person {
// fileds and methods
}
/**
* The public name of a hero that is common knowledge
*/
private String heroName;
/**
* <p>This is a simple description of the method ...
* <a href="http://www.supermanisthegreatest.com">Superman!</a>
* </p>
* @param incomingDamage the amount of incoming damage
* @return the amount of health hero has after attack
* @see <a href="Http://www.link_to_jira/HERO-402">HERO-402</a>
* @since 1.0
*/
public int successfullyAttacked(int incomingDamage) {
// do something
return 0;
}
참고
해당 포스팅은 제로 베이스 클린코드 한달한권을 수강 후 정리한 내용입니다.
Author And Source
이 문제에 관하여(클린코드 핵심 정리 (4장 주석)), 우리는 이곳에서 더 많은 자료를 발견하고 링크를 클릭하여 보았다
https://velog.io/@coconenne/클린코드-핵심-정리-4장-주석
저자 귀속: 원작자 정보가 원작자 URL에 포함되어 있으며 저작권은 원작자 소유입니다.
우수한 개발자 콘텐츠 발견에 전념
(Collection and Share based on the CC Protocol.)
해당 포스팅은 제로 베이스 클린코드 한달한권을 수강 후 정리한 내용입니다.
Author And Source
이 문제에 관하여(클린코드 핵심 정리 (4장 주석)), 우리는 이곳에서 더 많은 자료를 발견하고 링크를 클릭하여 보았다 https://velog.io/@coconenne/클린코드-핵심-정리-4장-주석저자 귀속: 원작자 정보가 원작자 URL에 포함되어 있으며 저작권은 원작자 소유입니다.
우수한 개발자 콘텐츠 발견에 전념 (Collection and Share based on the CC Protocol.)