[Java] 프로젝트 별 주석 활용법

학창시절 아침 0교시부터 야간 자율학습까지

엄청난 일정을 소화하면서

인고의 시간을 이겨내며 배운 것들도

 

지금 다시 고등 수학, 과학 문제를 보면

그때는 내가 이걸 어떻게 풀었나 감탄하게 되는데

코드도 똑같아서 다시보면 기억이 안난다.

 

다시 봐도 그땐 어떻게 버텼는지 신기하다.

 

이때 주석이 없으면

고대 유물을 연구하는 고고학자가 되기 십상인데

이런 고통을 겪고 싶지 않다면

 

10년뒤에 봐도 알아볼 수 있도록

주석을 잘 적어두는게 좋다.

 

그럼 어떻게 주석을 적는게 좋은가.

 

사실 주석은 글쓰기처럼

사람마다 다 스타일이 달라서

정해진 양식이 없다

 

그래서 회사, 프로젝트 마다

서로 협의해서 양식 가이드를 구성한다.

 

그래도 좋은 글쓰기의 기준이 있는것처럼

필자가 생각하는 좋은 주석 기준을 기술해본다.

 

만약, 주석 사용법이 기억안나면 아래 글부터 먼저 보고오자

Java 주석 사용법

 

 

1. 개인 프로젝트

 

자신이 봤을 때 한눈에 보기 쉽게 작성하는게 좋다.

개인 프로젝트를 한다는건 취업, 이직 준비를 하거나

관심 분야의 토이 프로젝트를 하는 경우가 많은데

 

혼자 대부분의 기능을 개발하므로

어지간한 내용은 자신의 머리속에 있고

원하지 않아도 몸이 기억하기에

나중에 봤을 때 이해할 수 있을 정도면 된다.

 

 

2. 팀 프로젝트

 

다른 개발자와 협업할 때는

동료가 내 코드를 보고 기능이나 동작 구조를 오해하지 않도록

주석을 상세히 작성해주는게 좋은데

 

메서드의 입출력 파라미터 형식, 값이나

클래스의 생성 목적 등

API 문서처럼 기재해주면 좋아한다.

 

같은걸 경험해도 사람마다 느끼는게 다르듯이

분명 같은 코드인데 다른 동작으로 이해하는 경우가 있다.

 

이런 경우에는 옆에서 버그가 미친듯이 발생하게 되는데

이러면 이제 집에 못가고 야밤의 등대가 되는것이다.

 

가장 중요한건 책임 소재를 명확히 할 수 있는데

꼬인 실타래마냥 복잡하게 얽힌 소스코드 속에서

원인을 명확히 알아야 고치든 할거 아닌가.

 

 

3. 회사 프로젝트

 

회사마다 작성 양식이 달라서

보통 PM, PL, 사수가 주석 작성 가이드를 알려줄 텐데

 

만약 어느 누구도 알려주지 않는다면

이전에 인수인계 받은 파일의 주석 양식이나

주석을 쓰는 다른 개발자의 코드를 보면서

괜찮은 양식을 참고하는게 좋다

 

 작성 일자, 소스코드 파일, 작성자, 문의 이메일

보통 4가지는 필수로 기재된다.

 

/*
 * Date   : 2022.11.02
 * Source : JavaStudy.java
 * Author : 홍길동
 * E-mail : honggildong@gmail.com
 * 
 * 코드 내용 기재
 */

 

주석을 잘 활용하면

협업하기 수월하고 유지보수에 용이하지만

 

어디까지나 코딩을 수월하게 하기위한 보조 역할이지

이것에 몰두해서 기능 구현을 뒷전에 두면

 

상사와 사수가 아수라가 되어 당신을 탈탈 털것이므로

본말전도가 되면 안된다.