프로그램 실행과는 상관없이 코드에 설명을 붙이는 문장이 주석이고, 이름과 형식을 어떻게 쓸지 미리 맞춰둔 약속이 코딩 컨벤션이다.
주석 세 가지 꼴
//는 그 자리부터 줄 끝까지, /* ... */는 두 기호 사이의 내용 전부를 주석으로 만든다. 여기에 JavaDoc 주석문이라고 따로 부르는 /** ... */가 있다.
JavaDoc으로 문서 뽑기
JavaDoc이 특별한 이유는 이 주석에서 문서를 뽑아낼 수 있어서다. 주석 안에 태그를 달아두면 그것을 읽어 HTML 문서를 만든다.
/**
* 책 한 권의 정보를 담기 위한 클래스
*
* @author jaeyoon
* @since 2023.03
* @version 0.1
*/
public class Book {
/**
* 책의 제목을 반환한다.
* @return 책의 제목
*/
public String getName() { return title; }태그는 각각 무엇을 적는 자리인지가 이름에 드러난다. @version은 버전, @author는 작성자, @since는 언제 생기거나 수정되었는지를 적는다. @deprecated는 더 이상 쓰지 말라는 표시이고, @see와 @link는 다른 필드나 메서드, 외부 링크로 이어준다. 발생할 수 있는 예외는 @exception에 적는다.
인텔리제이에서는 shift를 두 번 눌러 generate javaDoc을 찾으면 된다. 문서를 만들 패키지나 클래스를 고르고 출력 경로를 정한 다음, 명령행 인자에 -encoding UTF-8 -charset UTF-8 -docencoding UTF-8을 넣어야 한글이 깨지지 않는다. 공개 API를 만들 때 값어치가 큰데, 코드와 문서가 같은 자리에 있으니 함께 갱신되기 때문이다.
이름과 형식 규칙
컨벤션 쪽은 규칙이 짧다. 클래스 이름은 대문자로 시작하고 패키지 이름은 전부 소문자다. 변수와 메서드 이름은 소문자로 시작하되 길어지면 카멜 표기법으로 단어를 구분한다. public 클래스는 파일 하나에 하나만 두고 그 이름을 파일 이름과 같게 맞춘다. 마지막 규칙은 컨벤션이라기보다 문법이다. 어기면 아예 컴파일되지 않는다.
무엇이 아니라 왜
주석에는 무엇을 하는지가 아니라 왜 그렇게 했는지를 적는다. 코드가 이미 말하고 있는 것을 한 번 더 적으면 읽는 사람의 시간만 쓴다.
// i를 1 증가시킨다 ← 코드가 이미 말하고 있다
// 0번 인덱스는 헤더라 건너뛴다 ← 코드가 말하지 못하는 것주석보다 이름
주석이 필요하다고 느껴지면 이름부터 고칠 수 없는지 본다. 클래스, 메서드, 변수 이름만으로 이해되는 코드가 주석이 잘 달린 코드보다 낫고, 그러고도 남는 설명만 JavaDoc으로 적는다. 틀린 주석은 없느니만 못하다. 코드는 바뀌었는데 주석이 그대로면 읽는 사람을 속인다.
컨벤션이 못 정해주는 것
컨벤션은 형식을 맞춰줄 뿐이고 정작 어려운 것은 무엇이라 부를지다. 이름과 맞지 않는 속성이나 기능이 붙어 있으면 그 객체는 책임이 하나가 아니다(좋은 객체). 서비스 메서드 이름은 기획자와 이야기할 때 쓰는 말과 같아야 하고(유비쿼터스 언어), setPassword() 대신 updatePassword()라고 쓰면 무엇을 하는 변경인지가 이름에 드러난다(캡슐화와 정보 은닉).