주석(Comment)
컴퓨터 프로그램의 소스 코드에 추가 되는 설명
목적
주석을 통해 프로그램을 이해하는데 도움이 되는 정보를 제공하고 코드를 살펴보는 데 소요되는 시간을 단축하기 위한 용도로 사용하며
컴파일 시에는 실행되지 않아 프로그램에는 영향을 주지 않는다.
기능 & Plugin
- Code Template : Intellij 제공 기능으로 새 파일 생성 시 사전 정의된 템플릿을 제공하는 기능
- JavaDoc : JDK와 함께 패키지로 제공되는 도구, Java 소스 코드 문서를 생성하는데 도움을 주는 도구
Template 설정
1. 클래스 (Class)
※ Class 주석의 경우 JavaDoc을 사용해도 가능하나 원하는 템플릿으로 사용하기 위해 Code Template을 통해 사용
1.1 Template 설정 (Code Template)
1. IntelliJ > Preferences > Editor > File and Code Templates
2. Files > Class > Includes > File Header 내용을 통해 Template 수정
3. Class File 생성
1.2. 사전 정의 변수 (Template Predefined Variable)
- ${PACKAE_NAME} : 대상 패키지의 이름
- ${PROJECT_NAME} : 현재 프로젝트 이름
- ${NAME} : 대상 파일 이름
- ${USER} : 현재 사용자의 로그인 이름
- ${DATE} : 현재 시스템 날짜
- ${TIME} : 현재 시스템 시간
※ Reference Link 통해 더 많은 변수를 확인 할 수 있습니다.
2. 메소드 (Method)
2.1. Template 설정 (JavaDoc)
1. JavaDoc Plugin 설치 : IntelliJ > Preferences > Plugins > JavaDoc 검색 > 설치
2. JavaDoc Template Add : Intellij > Preferences > Tools > JavaDoc > Templates > Method level 정규식을 통해 Template 수정
3. JavaDoc 실행 : Intellij > Preferences > Keymap > JavaDoc > Create JavaDocs for the selected element 단축키 설정
2.2. 사전 정의 변수 (Template Predefined Variable)
- @deprecated : 더 이상 사용하지 않는 케이스
- @throws : 던지는 예외와 예외가 던져지는 케이스
- @param : 파라미터의 의미
- @return : 리턴값에 대한 의미
- @author : 작성자
※ Reference Link 통해 더 많은 변수를 확인 할 수 있습니다.
마치며 (개인적인 생각)
올해 11월에는 팀에 새로운 신입 개발자분들이 합류하면서 사수가 되었다. 이전에 스타트업에서 혼자 일하거나 프리랜서로 일하는 동안에는 개인적으로 주석을 설정하여 사용하였으나 주석에 대한 내용을 따로 정리할 필요가 없다고 생각했었다. 혼자 사용할 당시에는 따로 템플릿없이 사전 정의 변수 중 몇가지만 사용하거나 필요한 몇가지만 사용해왔지만 시스템이 점점 커지고 있기도 하고 신입 팀원들에게 내 코드를 이해시키기 위해서는 템플릿화된 주석이 필요하다고 느끼게 되었다. 신입 팀원들에게 프로젝트의 전반적인 프로세스부터 소스 리뷰까지 공유하며 협업을 시작하다보니 주석에 대한 중요성도 알려주고, 겸사겸사 팀원들에게도 리뷰 해주기 위해 Intellij에서 주석 작성에 대한 내용을 정리해 보았다. 또한, 주석은 많은 장점을 가지고 있지만, 업데이트되는 항목들에 대해 관리를 하지 않거나 작성자가 아닌 협업자들이 이해하지 못하도록 작성하거나 너무 많은 양이면 장점들이 사라질 것 같다.
주석은 최대한 이해하기 쉽고 함축적으로 필요한 정보만 작성하는게 좋을 것 같다.
