Comment에 대한 고찰

---

2023.08.02 - [IT/고찰] - Commit Message에 대한 고찰

Commit Message에 대한 고찰에 이은 고찰 시리즈 2탄

---

 

사실 주석은 필요하지 않다

로버트 C 마틴의 Clean Code 책에서 주석은 필요 악인 존재입니다. 주석은 코드로 의도를 표현하지 못해서 남기는 것이라 말하기도 합니다.

2021.10.30 - [IT/책] - [Clean Code] 4장, 주석

[Clean Code] 4장, 주석

 

그리고 주석을 지양해야 하는 이유로 제시된 근거는 프로젝트를 하면서 실제로도 꽤 많이 공감이 되었습니다.

1. 주석은 유지보수하기에 어려움
2. 주석이 코드를 항상 따라가지 않음
3. 부정확한 주석은 없는 주석보다 훨씬 나쁨

 

코드는 반드시 의미를 가진 채로 남지만, 주석은 처음 적었던 의도를 잃기 쉽습니다. 그리고 무분별한 주석은 오히려 가독성을 떨어뜨립니다.

즉, 가장 좋은 것은 주석이 필요 없을 정도로 잘 읽히는 프로그래밍 코드입니다.

---

Comment

필요성

그렇지만 주석이 없어야만 하는 존재인 것은 아닙니다. 주석이 필요 없을 정도로 완벽한 코드를 작성하기는 매우 어렵습니다. 또한, 코드에 모두 나타낼 수 없는 정보들(법, 정규표현식, 시간, 날짜 등)은 주석으로 설명을 해야합니다.

 

결국 주석은 코드가 말하고자 하는 것이 명확하지 않을 때 사용하는 것이 가장 효과적입니다.

1. 직관적으로 표현하기 힘든 것
2. 왜 하는 지 설명이 필요할 때

 

 

좋은 주석

좋은 주석은 1. 유지보수가 쉽고 2. 통일성이 있어야합니다. 이전 글인 Commit Message와 어느정도 일맥상통하는 내용도 존재합니다. 결국, 읽기 쉬워야 한다는 것이 가장 핵심입니다. 정렬된 Message일 수록 내가 말하고자 하는 바를 명확하게 표현 할 수 있습니다.

 

 

문서 주석

https://6kkki.tistory.com/1

- JaevaDoc을 작성할 때 사용됩니다.

- "/**           */"로 경계가 결정됩니다.

- 클래스, 인터페이스, 함수 등의 단위로 각 역할에 대해서 설명(or Summary)하는 데 사용됩니다.

 

1. Class/Interface

import java.util.*

/**
* 해당 클래스가 가지는 기능과 용도를 설명
*
* <pre> 상세 설명 </pre>
* @author
* @version
* @그 외 필요한 내용들
*/


@Service
public class commentService{
 ...
}

 

2. Method

/**
* 메서드 기능 설명
*
* @param requestDTO 파라미터 설명
* @returnType RetrunDTO 반환 설명
* @exception 예외
*/
public RetrunDTO commentMethod(RequestDTO requestDTO){
  ...
}

 

 

잘 작성된 JavaDoc은 코드를 이해하는 것에 대해 효과적인 도움을 줍니다.

 

https://johngrib.github.io/wiki/java/javadoc/

Javadoc 작성하기

1. 가독성이 가장 중요함
2. 특정 메소드나 클래스의 책임을 3초안에 파악할 수 있도록 짧고 간결하게
3. 구현에 대해서는 설명하지 않음

위 블로그에서 자세하게 예시를 확인할 수 있습니다.

 

 

구현 주석

- /* * 또는 //로 작성됩니다.

- 혼란을 없앨 수 있는 명확한 내용을 담는 것이 중요합니다. 유지보수하기 어려운 주석들은 반드시 지양해야 합니다.

- 코드만으로는 확인할 수 없는 내용을 적는 것이 핵심 포인트!

 

주석 잘 활용하기

[자바 코딩의 기술] 3. 주석 잘 활용하기

 

1. 생각 기록하기

/*
* 대량 가입 시, 서버 성능 문제가 발생하여 한 번에 3000개 이상을 처리하지 못한다.
* 이벤트를 나눠서 처리하여 해결한다.
*/

 

2. 결함 설명하기

//TODO: 앞으로 보강되어야 하는 내용

 

3. 상수에 대해 설명

int MAX_EVENT = 100; //최대 이벤트는 100개이다.

if(size < MAX_EVENT){
  ...
}

 

- MAX_EVENT라는 상수로 해당 내용을 코드로 설명
- MAX_EVENT를 설명하는 주석을 구현 코드에 포함시키지 않음

 

4. 결과를 경고하는 주석

/*
* 코드 실행 시, 00분정도의 시간이 소요된다.
*/

- 결과를 경고하여 해당 테스트를 실행하지 않도록 조심하거나 하염없이 기다리는 행위 등을 최소화 할 수 있음

 

 

5. 그 외, 원본/참고 링크 등을 주석으로 활용

 

 

나쁜주석

주석에 대한 많은 내용들이 나쁜 주석에 대해서 설명을 합니다. 그만큼 주석을 남용하는 사례들이 많다는 것을 이야기 하기도 합니다.

 

1. 대부분의 주석은 코드가 하는 말을 반복하는 경우가 많습니다.
if( n <  3 ) 이라는 내용에 대해서 "n이 3보다 작을때"와 같이 코드로 드러나는 내용을 다시 알려줄 필요는 없습니다.

 

2. 모호한 코드를 변명하지 않습니다.
주석이 코드를 변명해야 한다면, 코드를 직접적으로 수정해야 합니다. 변수 명을 변경하거나, 함수를 더욱 쪼개서 함수 이름으로 설명 할 수도 있습니다.

 

3. 주석으로 처리된 코드, 이력을 기록하는 주석들은 불필요한 주석이므로 삭제되는 것이 좋습니다.
옛날 코드들이 아까울 수 있지만, 해당 기록들은 git과 같은 형상관리 툴로 충분히 관리가 가능합니다.

---

 

혹시 모를 상황에 대비하여 남겨두는 주석들은 오히려 유지보수를 어렵게 만들고 이후 혼란을 야기합니다. 그러나 너무 적은 주석 역시 코드 가독성을 떨어뜨리기도 합니다. 많은 개발자들이 읽기 쉬운 코드를 작성할 수 있는 것은 아니기 때문입니다. 

 

 

 

 

참고문헌

https://danpatpang.github.io/tip/2018/04/12/Tip_java_comment/

https://johngrib.github.io/wiki/java/javadoc/#%ED%95%A8%EA%BB%98-%EC%9D%BD%EA%B8%B0-reduce-technical-debt-by-valuing-comments-as-much-as-code

https://developside.tistory.com/14

https://kukuta.tistory.com/388