[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);
✍️ 좋은 주석 작성 팁
| ❌ 나쁜 예 | ✅ 좋은 예 |
| // 버튼 클릭 | // 사용자가 로그인 버튼을 클릭했을 때 처리되는 이벤트 |
| // 계산함 | // 할인율과 쿠폰을 반영하여 최종 금액 계산 |
✔️ “왜”를 설명하는 주석을 쓰세요.
- “무엇을 한다”보다 “왜 이렇게 했는지”가 더 중요합니다.
✔️ 유지보수 기준으로 적으세요.
- 나중에 다른 사람이 봤을 때 도움이 되어야 합니다. 자기 자신 포함!
❌ “당연한 코드 설명”은 쓰지 마세요.