[Java] 주석의 종류와 사용법

목차

 

 

주석은 코드의 동작에는 영향을 주지 않지만, 코드를 읽는 사람에게 큰 도움을 주는 아주 중요한 요소입니다.

이번 글에서는 Java에서 사용되는 주석의 종류와 실제 사용 예시, 그리고 좋은 주석을 작성하는 팁까지 함께 정리해볼게요.

---

주석이란?

주석이란 코드 내에 설명, 기록, 메모, TODO 목록 등을 남기는 도구로, 실행 시 무시됩니다.
즉, 컴파일러나 JVM은 주석을 완전히 무시합니다.

---

🔸 Java 주석의 종류

Java에서는 총 3가지 종류의 주석을 사용할 수 있습니다.

 

1. 한 줄 주석 (//)

한 줄 전체를 주석 처리할 때 사용합니다. 가장 많이 쓰이며, 빠르게 메모할 때 유용하죠.

int age = 30;  // 나이 변수 선언

💡 Tip: 디버깅 시 System.out.println()을 임시로 주석 처리할 때도 자주 사용됩니다.

 

2. 여러 줄 주석 (/ /)

여러 줄에 걸친 설명이 필요하거나, 특정 블록을 전체 주석 처리하고 싶을 때 사용합니다.

/*
 이 부분은
 나중에 리팩토링할 예정입니다.
 */
String name = "Java";

또는 코드 블록 전체를 주석 처리할 때도 활용됩니다

/*
if (isTest) {
    runTestMode();
}
*/

 

3. 도큐먼트 주석 (/ /)*

Java는 도큐먼트 주석을 사용해, 소스 코드만으로도 API 문서를 자동 생성할 수 있습니다.

도큐먼트 주석은 클래스, 메서드, 필드 등에 작성하면, javadoc 명령어를 통해 HTML 형태의 문서로 출력할 수 있어요.

/**
 * 사용자의 이름을 반환하는 메서드입니다.
 *
 * @return 사용자 이름
 */
public String getUserName() {
    return name;
}

 

🏷️ 자주 사용하는 Javadoc 태그

태그	용도	예시
@param	메서드의 매개변수를 설명할 때	@param name 사용자 이름
@return	메서드가 반환하는 값을 설명할 때	@return 전체 금액
@throws 또는 @exception	예외가 발생할 수 있는 경우 설명	@throws IllegalArgumentException 잘못된 입력일 때
@see	참고할 클래스나 메서드 링크	@see java.util.List
@deprecated	더 이상 사용되지 않음을 명시	@deprecated v2.0부터 제거 예정
@author	작성자 명시	@author 혜빈
@version	버전 정보	@version 1.2.0
@since	언제부터 도입되었는지	@since 1.5

📌 이 주석은 라이브러리, 프레임워크, API 문서화를 할 때 사용됩니다.

---

🛠 주석은 어떻게 쓸까?

✅ 설명 주석

• 복잡한 로직의 핵심 의도나 알고리즘을 설명할 때

// 이진 탐색으로 타겟 인덱스를 찾는다

 

✅ TODO 주석

• 아직 구현하지 않은 기능이나 개선할 부분을 표시할 때

// TODO: 예외 처리 로직 추가할 것

 

✅ DEBUG 주석

• 임시로 디버깅용 코드를 남겨두고자 할 때

// System.out.println("값 확인: " + value);

---

✍️ 좋은 주석 작성 팁

❌ 나쁜 예	✅ 좋은 예
// 버튼 클릭	// 사용자가 로그인 버튼을 클릭했을 때 처리되는 이벤트
// 계산함	// 할인율과 쿠폰을 반영하여 최종 금액 계산

✔️ “왜”를 설명하는 주석을 쓰세요.

• “무엇을 한다”보다 “왜 이렇게 했는지”가 더 중요합니다.

✔️ 유지보수 기준으로 적으세요.

• 나중에 다른 사람이 봤을 때 도움이 되어야 합니다. 자기 자신 포함!

❌ “당연한 코드 설명”은 쓰지 마세요.