Java 주석 작성법 완벽 가이드: 한 줄 주석부터 블록 주석까지

코딩을 할 때 가장 먼저 떠오르는 것은 컴퓨터가 작성한 코드를 어떻게 처리하는가일 것입니다. 하지만 사람들이 여러분의 코드를 어떻게 읽을지 생각하는 것 역시 매우 중요합니다.

팀 프로젝트를 진행하든 혼자 무언가를 만들든, 코드를 적절히 문서화하는 노력이 필요합니다. 바로 이때 주석(comment)이 필요합니다.

주석이란 프로그램 내에 작성된 한 줄 또는 여러 줄의 텍스트로, 컴퓨터는 이를 무시합니다. 주석은 코드를 읽는 사람, 즉 본인이나 다른 개발자에게 프로그램의 의도를 설명하기 위해 사용됩니다.

이 글에서는 Java에서 주석을 작성하는 방법과 함께, 효과적인 주석을 작성하기 위한 모범 사례까지 살펴보겠습니다.

Java 주석이란?

프로그래밍을 처음 시작한다면 "왜 굳이 코드에 주석을 달아야 할까?"라는 의문이 들 수 있습니다. 코드 주석이 중요한 이유는 몇 가지가 있습니다.

코드를 작성할 때는 반드시 그 코드를 누군가 읽게 된다는 점을 인식해야 합니다. 설령 그 독자가 미래의 자기 자신일지라도 말입니다. 게다가 코드를 읽는 사람이 작성된 코드를 반드시 이해할 것이라는 보장은 없습니다.

혼자 작업할 때 주석 없는 코드는 답답함을 유발하고, 코드의 동작 방식을 다시 파악하는 데 시간을 낭비하게 만듭니다. 팀으로 작업할 때는 주석이 없으면 문제가 더욱 심각해집니다. 다른 개발자들이 코드에 대해 일일이 물어봐야 할 수 있고, 이는 소중한 시간을 소모하게 됩니다.

전반적으로 주석을 작성하면 코드 가독성이 크게 향상됩니다. 복잡한 로직을 작성할 때는 코드 옆에 간단한 설명을 덧붙여 특정 코드의 의도를 밝혀두는 것이 좋습니다. 작성해 둔 주석은 특히 여러 개발자와 함께 프로젝트를 진행할 때 훌륭한 참고 자료가 됩니다.

최고의 주석은 코드의 의도를 설명하는 것입니다. 특정 방식으로 구현한 '이유'를 설명하고, 단순히 코드가 무엇을 하는지 반복해서 적지 마세요. 효과적인 주석은 궁금증을 해소하고 업무 효율을 높여줍니다.

Java 주석 문법

Java에서 작성할 수 있는 주석에는 두 가지 유형이 있습니다. 바로 한 줄 주석(single-line comment)과 여러 줄 주석(multi-line comment)입니다.

한 줄 주석(Single-Line Comments)

한 줄 주석은 인라인 주석(inline comment)이라고도 불리며, 코드 줄 끝에 위치합니다.

인라인 주석은 보통 한두 줄 정도의 짧은 코드에 설명을 붙일 때 사용됩니다.

예를 들어, 콘솔에 "It's Friday" 메시지를 출력하는 프로그램을 작성하면서 코드를 추적하기 위해 주석을 추가한다고 가정해 보겠습니다. 사용할 수 있는 인라인 주석의 예는 다음과 같습니다.

public class FridayMessage {
	public static void main(String[] args) {
		System.out.println("It's Friday!"); // 콘솔에 "It's Friday" 출력
	}
}

인라인 주석은 특정 코드 줄의 의도를 설명해야 할 때만 사용해야 합니다. 인라인 주석이 너무 많으면 코드가 오히려 읽기 어려워질 수 있습니다.

주석을 작성할 때 목표는 코드의 의도를 설명하는 것이어야 한다는 점에 유의하세요. 위 예제의 주석은 사실 그다지 유용하지 않습니다. 코드가 하는 일을 누구나 쉽게 알 수 있기 때문입니다. 하지만 더 복잡한 코드라면 주석이 실질적인 도움을 줄 수 있습니다.

여러 줄 주석(Multi-Line Comments)

여러 줄 주석은 블록 주석(block comment)이라고도 불리며, 코드 섹션 전체를 설명하는 데 사용됩니다. 여러 줄에 걸쳐 작성되며, 보통 파일 상단이나 코드 블록이 시작되기 전에 배치됩니다.

여러 줄 주석은 /*로 시작하여 */로 끝납니다. Java 소스 파일에서 여러 줄 주석의 예는 다음과 같습니다.

/* 여러 줄 주석 예제입니다.
   아래 코드는 콘솔에 "It's Friday!"를 출력합니다.
*/

public class FridayMessage {
	public static void main(String[] args) {
		System.out.println("It's Friday!");
	}
}

이 예제에서 주석은 코드의 처음 세 줄에 위치합니다.

여러 줄 주석은 파일 시작 부분에 파일 자체에 대한 정보를 기록하는 용도로 자주 사용됩니다. 예를 들어 파일 작성자, 버전 정보 등을 포함할 수 있습니다.

테스트를 위한 코드 주석 처리

주석은 문서화 수단일 뿐만 아니라, 소프트웨어 개발의 테스트 및 디버깅 단계에서 특정 코드의 실행을 임시로 막는 용도로도 활용됩니다. 개발자들은 이를 '코드 주석 처리(commenting out)'라고 부릅니다.

예외(exception)가 발생하는 프로그램을 작성하고 있다고 가정해 보겠습니다. 아직 원인을 확실히 알 수 없다면, 문제의 원인을 좁히기 위해 코드 일부를 주석 처리해 볼 수 있습니다. 다음은 코드를 주석 처리하는 예입니다.

class FridayMessage {
	public static void main(String[] args) {
		String day_of_the_week = "Friday";
		// System.out.println("It's " ++ day_of_the_week);
	}
}

이 예제에서는 System.out.println으로 시작하는 코드 줄을 주석 처리했습니다. 코드가 오류를 반환했고(++ 연산자를 잘못 사용함), 오류의 원인을 파악하는 동안 해당 코드를 주석 처리해 둔 것입니다.

주석 처리는 프로그램 로직을 분석할 때 특히 유용합니다. 이런 상황에서는 가장 효율적인 구현을 찾을 때까지 여러 버전의 코드를 주석 처리하며 비교해 볼 수 있습니다. 최적의 코드를 찾은 후에는 기존 코드를 삭제하면 됩니다.

단, 코드 주석 처리는 테스트와 디버깅 단계에서만 사용해야 합니다. 최종 프로그램에 주석 처리된 코드를 그대로 남겨두면 다른 개발자에게 혼란을 주고 코드 가독성도 떨어집니다.

결론

Java에는 한 줄(인라인) 주석과 여러 줄(블록) 주석이라는 두 가지 유형의 주석이 있습니다. 이러한 주석은 코드를 문서화하는 데 사용되며, 소프트웨어 개발의 테스트 및 디버깅 단계에서도 큰 도움이 됩니다.

코드에 주석을 다는 시간을 투자하면 본인과 코드를 읽는 모든 사람에게 더 읽기 쉬운 결과물을 제공할 수 있습니다. 마지막으로 기억할 점은, 최고의 주석은 코드의 의도를 설명하는 주석이라는 것입니다.

이제 여러분도 프로처럼 Java 주석을 작성할 준비가 되었습니다!