Java 주석: 한 줄, 여러 줄, Javadoc

주석은 무엇을 위한 것인가

주석은 Java 컴파일러가 완전히 무시하는, 소스 코드 안의 텍스트입니다. 실행되는 프로그램의 일부가 되는 일은 결코 없으며, 오직 코드를 읽는 사람을 위해서만 존재합니다. 주석은 어떤 것이 왜 특정한 방식으로 되어 있는지 설명하거나, 메모를 남기거나, 코드를 지우지 않고 일시적으로 비활성화할 때 사용합니다.

Java에는 세 종류의 주석이 있습니다. 한 줄 주석(//), 여러 줄 블록 주석(/* */), 그리고 Javadoc 문서 주석(/** */)입니다. 셋 다 컴파일 시점에 무시된다는 동일한 기본 역할을 하지만, 상황에 따라 각각을 골라 씁니다.

한 줄 주석

슬래시 두 개(//)는 현재 줄의 끝까지 이어지는 주석을 시작합니다. 컴파일러는 //부터 줄 바꿈까지 모든 것을 건너뜁니다.

public class Main {
    public static void main(String[] args) {
        // 콘솔에 인사말을 출력한다
        System.out.println("Hello, Java!");

        int score = 90; // 주석은 코드 뒤에 올 수도 있다
        System.out.println(score);
    }
}

두 번째 주석이 실제 코드와 같은 줄을 공유하고 있다는 점에 주목하세요. // 앞에 있는 모든 것은 여전히 실행되며, 그 뒤의 부분만 무시됩니다. 이것은 짧은 메모에 가장 흔히 쓰이는 주석 방식입니다.

여러 줄 블록 주석

메모가 여러 줄에 걸칠 때는, 각 줄 앞에 //를 붙이는 것보다 블록 주석이 더 깔끔합니다. 블록 주석은 /*로 시작해 */로 끝납니다. 그 사이에 있는 모든 것은 몇 줄이든 무시됩니다.

public class Main {
    public static void main(String[] args) {
        /*
         * 이 프로그램은 블록 주석을 보여 준다.
         * 각 줄 앞머리의 별표는 가독성을 위한
         * 관례일 뿐이며 필수는 아니다.
         */
        System.out.println("Block comments are handy.");
    }
}

왼쪽 가장자리를 따라 정렬된 * 문자는 규칙이 아니라 스타일 관례입니다. 실제로 의미가 있는 부분은 시작하는 /*와 닫는 */뿐입니다.

코드 주석 처리하기

주석은 실험하는 동안 코드를 지우지 않고 비활성화하는 표준적인 방법입니다. 한 줄에는 //를, 여러 줄을 한 번에 끄려면 블록 주석을 사용하세요.

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

실행하면 "runs"가 들어간 두 줄만 출력되는 것을 볼 수 있습니다. 주석 처리된 println 호출은 컴파일러에게 보이지 않습니다.

흔한 함정: 블록 주석은 중첩되지 않습니다. 앞에 /*가 몇 개 있든, 첫 번째 */가 주석을 닫습니다. 그래서 /* ... */ 블록을 다른 /* ... */ 블록 안에 감쌀 수 없습니다. 안쪽 */가 전체를 끝내 버리고 나머지는 구문 오류가 됩니다. 이미 블록 주석을 포함하고 있는 영역을 비활성화해야 한다면, 각 줄에 //를 사용하세요(대부분의 편집기는 단축키 하나로 이를 처리해 줍니다).

Javadoc 문서 주석

Javadoc 주석은 블록 주석처럼 보이지만 /**(별표 두 개)로 시작합니다. 클래스·메서드·필드를 문서화하기 위한 것이며, 설명 대상 바로 위에 놓입니다. javadoc 도구는 이를 탐색 가능한 HTML API 문서로 바꾸고, IDE는 마우스를 올렸을 때 툴팁으로 보여 줍니다.

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

@param, @return, @throws 태그는 도구가 이해하는 구조화된 필드입니다. 컴파일러에게는 여전히 무시되는 주석일 뿐이며, 그 가치는 전적으로 도구가 생성하는 문서와 IDE가 다른 개발자(그리고 6개월 뒤의 자신)에게 제공하는 힌트에 있습니다.

좋은 주석과 잡음

주석은 코드가 스스로 말할 수 없는 무언가를 설명해야 합니다. 단지 코드를 되풀이하기만 하는 주석은 잡동사니를 더하고, 코드가 바뀌면서 오래된 정보가 되기 쉽습니다.

// 나쁨: 코드가 분명히 하는 일을 그저 반복함
int i = i + 1; // i에 1을 더한다

// 더 나음: 코드가 보여 줄 수 없는 이유를 설명함
retries++; // 잠시 물러났다가 재시도; API는 초당 5요청으로 제한됨

명확한 이름과 구조를 통해 코드 자체를 읽기 쉽게 만들고, 주석은 이유를 위해 아껴 두세요. 의도, 절충점, 예외 상황, 맥락으로 향하는 링크 같은 것들 말입니다. 헷갈리는 한 줄을 설명하려고 주석을 쓰고 있는 자신을 발견했다면, 그것은 대개 변수 이름을 바꾸거나 메서드를 추출하라는 신호입니다.

다음: 변수

이제 코드에 주석을 달 수 있게 되었으니, 다음 구성 요소는 그 안에 데이터를 저장하는 것입니다. 다음 페이지에서는 변수를 다룹니다. 변수를 어떻게 선언하는지, 변수가 담는 타입은 무엇인지, 그리고 Java가 정적 타입 언어이기 때문에 강제하는 규칙들에 대해 알아봅니다.