[Clean Code] 클린 코드 'Chapter 4. 주석' 핵심 내용 및 정리

도서 목차

Chapter 1. 깨끗한 코드
Chapter 2. 의미 있는 이름

Chapter 3. 함수

 

Chapter 4. 주석

(p67 ~ 94)

 

Chapter 5. 형식 맞추기

Chapter 6. 객체와 자료 구조

Chapter 7. 오류 처리

Chapter 8. 경계

Chapter 9. 단위 테스트

Chapter 10. 클래스

Chapter 11. 시스템

Chapter 12. 창발성

Chapter 13. 동시성

Chapter 14. 점진적인 개선

Chapter 15. JUnit 들여다보기

Chapter 16. SerialDate 리팩터링

Chapter 17. 냄새와 휴리스틱

 

강의 목차

코드를 보조하는 주석

01 주석을 최대한 쓰지 말자
02 좋은 주석
03 주석보다 annotation
04 JavaDoc

 

01 주석을 최대한 쓰지 말자

- 주석은 나쁜 코드를 보완하지 못한다.

코드에 주석을 추가하는 일반적인 이유는 코드품질이 나쁘기 때문이다.
자신이 저지른 난장판을 주석으로 설명하지 말고 개선하는데 시간을 보내야 한다.
코드로도 의도를 표현할 수 있다

 

 

- 주석은 방치된다.

코드의 변화에 따라가지 못하고, 주석은 방치된다.
코드는 컴파일되어 호출되지만, 주석은 그저 주석이기 때문에 그 자리에 방치되고 결국의미 없는 텍스트가 되어버린다.

 

02 좋은 주석

- 구현에 대한 정보를 제공

 

- 의도와 중요성을 설명

 

- TODO, FIXME 주석 (Task tag)

• TODO : 좀 더 최적화시키고 리팩터링 시킬 수 있을만한 구석이 있을 때.
• FIXME : 문제가 있는 것이 확실하지만, 그걸 지금 당장 그것을 수정할 필요는 없을 때.
IDE에서 하이라이팅 되고, 별도의 창에서 관리할 수 있다.

https://string.tistory.com/104

[Eclipse] Task tag란? Task tag의 종류

 

03 주석보다 annotation

annotation = 코드에 대한 메타데이터
코드의 실행 흐름에 간섭을 주기도 하고, 주석처럼 코드에 대한 정보를 줄 수 있다.

 

- 자주 사용되는 annotation

java.lang.annotation
@Deprecated: 컴파일러가 warning을발생시킴. 사용시 IDE에서 표시됨
@NotThreadSafe: ThreadSafe 하지 않음을 나타냄 (주석보다 어노테이션으로 많이 사용)

 

04 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 {
    // fields 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 things
    return 0;
}

 

- Javadoc 문서

https://www.baeldung.com/javadoc

 

 

 

 

 

 

 

ref.

https://www.baeldung.com/javadoc