최근 우리 공저자 중 한 명인 Joerg가 다양한 앱과 스트리밍 서비스가 딸려 있고 다양한 방식의 시간 기반 녹화가 가능한 새 스마트 TV를 샀습니다. 알고 보니 그 스마트 TV는 그 TV를 사용하는 사람만큼만 똑똑해 새로운 기능을 동작시키는 방법을 모두 배우는 것이 결코 쉽지 않았습니다. TV가 녹화본을 어느 폴더에 저장했는지 찾다가 욕설만 몇 개 터득하기에 십상이었죠. 게다가 전원 버튼을 누르면 녹화가 중지된다는 경고를 왜 미리 해주지 않았을까요?

바로 그때 사람들은 대부분 사용 설명서를 찾습니다. 사용 설명서는 명확히 알려주는 문서입니다. 녹화본을 어디서 찾을 수 있는지, 방송을 시청하지 않으면서 어떻게 녹화하는지 등을 가르쳐 줍니다. 하지만 이 스마트 TV는 사용 설명서를 익히다 불만만 커집니다. ‘녹화 버튼’ 항목에는 “녹화를 시작합니다”라고만 나옵니다. 누구든지 빨간색 녹화 버튼만 보아도 그 정도는 알 거예요! 또한 녹화 도중에 전원 버튼을 누르면 어떻게 될까요? 아무 설명도 없습니다.

사용 설명서는 동작 방법을 알려주는 것입니다. 코드 내 주석도 마찬가지예요. 주석의 목적은 코드가 어떻게 동작하는지 알려줍니다. 불행히도 코드 주석은 종종 스마트 TV의 사용 설명서와 비슷해 별로 유용하지 않습니다. 예를 들어 이미 코드에 있는 내용만 반복하죠. 더 최악인 경우는 실제 코드와 다른 내용을 말하는 것입니다.

3장에서는 주석을 더 유용하게 만드는 방법을 배우겠습니다. 이어지는 페이지에서는 주석을 사용할 때와 주석을 피해야 할 때의 직감을 익혀 보겠습니다. 어떤 주석 유형이 불필요한지 보여주고 주석 처리된 코드로 무엇을 하는지 설명하고 주석을 코드로 대체할 때 사용할 수 있는 몇 가지 비결도 소개하겠습니다. 마지막으로 고급 JavaDoc 주석을 작성하기 위한 자바의 주석 규칙도 알아보겠습니다. 시작해 봅시다!