[Tip] 주석을 다는 방법

in Tip on tip

나의 프로젝트를 가장 잘 표현할 수 있는 것은 주석이다.
주석은 협업에 있어서 절대 뺄 수 없는 존재다.
이번 기회를 통해 주석을 작성하는 방법에 대해 알아보려고 한다.

Comment

주석을 달기 어려운 이유

주석은 얼마나 달아야 하는가?

가장 어려운 이유가 아닌가 싶다. 내 주석을 읽을 사람들이 어느 정도의 정보가 필요한지 파악하는 것은 엄청 어려운 일이다. 너무 적은 주석은 불친절하고 과도한 주석은 친절의 도를 넘어서게 된다. 과도한 주석은 코드의 가독성을 떨어뜨리게 되고 주석을 작성하는데 있어서 비용 또한 너무 많이 들어간다.

업데이트가 쉬워야 한다.

대부분의 프로젝트는 만드는 것보다 유지보수를 하는 데에 더 많은 시간과 노력을 필요로 한다. 기존의 코드에서 단 한 줄이라도 바뀌게 된다면 그 줄에 해당하는 내용은 모두 주석이 업데이트 되어야 한다. 주석에서 잘못된 설명이 적혀있다면 주석을 읽는 사람들에게 큰 혼란을 줄 것이다. 하지만 주석이 너무 많아도 문제일 것이다. 그래서 소스코드를 활용하고 유지보수하는데 있어서 어려움이 없도록 해야한다.

전체적으로 통일이 되어야 한다.

A 파일과 B 파일의 주석 형식이 다르다면 어떻게 될까? 코드를 살펴보는 데 있어서 큰 문제는 없을 것이다. 하지만 100개의 파일이 넘어가는 프로젝트라면 통일되지 않은 주석에 가독성이 떨어질뿐만 아니라 주석이 코드를 방해하게 된다. 디자인 패턴만큼 중요한 것이 주석을 작성하는 형식의 일관될 통일이 아닐까?

좋은 주석을 작성하는 방법

주석의 표준을 정해야 한다.

이후에 다룰 Javadoc 등의 표준 주석을 따르면 여러 툴의 많은 도움을 받을 수 있고 가독성이 높아진다. 나중에 누군가 나의 프로젝트에 참여하거나 내가 다른 사람의 프로젝트에 참여할 때도 널리 알려진 표준을 알고 있다면 쉽게 이해할 수 있을 것이다.

주석은 소스코드보다 먼저다.

주석은 코딩하면서 다는 것이 아니다. 프로젝트 과정에 있어서 설계는 굉장히 중요한 단계이다. 대부분의 학생들이 코드 작성이 끝나고 주석을 작성하는 습관이 있다. public function과 함께 주석을 먼저 작성해 놓으면 코딩을 하면서 구현이 쉬워진다. 또한, 내부의 코드가 자주 변경되더라도 핵심 내용의 주석만 담고 있으므로 주석을 수정하는 일은 발생하지 않을 수도 있다.

public function 위주로 주석을 단다.

모든 소스 코드에 주석을 다는 것은 미친 짓이다. 이유는 간단하다. 해 보면 알 것이다. 주석의 양은 많다고 좋은 것이 아니라 정보의 전달 정도가 중요하다. 소스 코드에서는 public function에 주석을 다는 것이 가장 효율적이지 않을까 싶다.

주석같은 소스코드가 좋다.

복잡한 소스 코드로 작성하고 주석으로 설명하는 것보다는 효율이 떨어져도 가독성 높게 코드를 풀어쓰는 것이 좋다. 성능에 목숨을 거는 알고리즘 개발이 아니라면, 가독성이 높은 코드가 더 좋다. 프로그램은 개발 비용보다 유지보수 비용이 더 크다는 것을 잊지 말자.

Prototyping 시에는 주석이 필요없다.

프로토타입은 주석, 에러처리 없이 가장 빠르게 프로젝트를 검증하는 것이다. 실제 개발할 프로젝트는 프로토타입보다 훨씬 많은 시간이 걸리기 때문에 개발 시 프로토타입은 버리고 처음부터 다시 개발할 필요가 있다. 어정쩡한 주석으로 인해서 프로젝트가 다른 길로 갈 수도 있다.

처음에는 강제화가 필요하다.

리뷰는 항상 중요하다. 나의 코드를 남에게 보여주는 것뿐만 아니라 남의 코드를 리뷰하면서 좋은 코드를 보고 배울 필요가 있다. 코드 리뷰보다는 설계 리뷰가 중요하다. 설계 단계에서 주석을 먼저 달아 놓는다면 코딩이 시작됐을 때 팀끼리 협업도 원활할 것이며 재작업도 줄어들 것이다.

주석의 종류

  • 문서주석 : /** */에 의해 경계가 결정된다. javadoc 툴을 사용하여 HTML 파일로 추출 가능하다.
  • 구현주석 : /**/와 //에 의해 경계가 결정된다. 개별적 구현에 대한 주석이나, 코드와는 상관없는 주석을 쓸 때 사용된다.

문서 주석

  1. -자바 클래스, 인터페이스, 생성자, 메서드, 필드 등을 설명 할 때 사용한다.
  2. /** */로 경계를 결정한다.
  3. 클래스, 인터페이스, 멤버 당 하나씩 넣는다.
  4. 선언 바로 전에 나와야 한다.
  5. 최상위 레벨의 클래스와 인터페이스들은 열여쓰기를 하지 않고 멤버들은 들여쓰기를 한다.
  6. 클래스에 대한 문서주석의 첫 번째 줄은 들여쓰기를 하지 않고 그 다음에 나오는 문서주석은 _별포를 수직으로 맞추고 1칸의 공백_을 둔다.
  7. 생성자에 대한 문서주석의 _첫 번째 줄은 4칸의 공백_을 두고 그 _이후부터는 5칸의 공백_을 둔다.
  8. 문서주석에 적절하지 않은 것에 대한 정보를 제공하려면 선언 바로 후에 block 주석이나 single line 주석을 사용한다. 단, _클래스의 구현에 대한 세부사항은 block 주석_을 사용한다.
  9. 자바는 문서주석을 주석 이후 처음 나오는 선언문과 연결시키므로 메서드, 생성자 정의 블록 내부에 위치하면 안된다.

클래스 설명 주석

  • import 다음에 기술
  • 블록주석을 사용
  • 각 라인은 *로 시작
  • 해당 클래스에 대한 기능과 용도 기술
  • <pre>...</pre> 내용은 수정하지 않음
/**
* Serialize 기능을 사용하여 file에 object 저장?
* 해당 클래스에 대한 기능과 용도를 적어줍니다.
* 
* @author 최종 수정자
* @version 1.0, 작업 내용
* @see None
*/

멤버변수 설명 주석

  • 변수 상단에 위치
  • 블록주석을 사용
  • 용도, 제한사항 등을 기술

멤버변수는 constant → static → primitive → reference 순서로 기술한다.

멤버함수 설명 주석

  • 함수의 상단에 위치
  • 블록주석을 사용
  • 메서드 기능 설명은 한, 두 줄로 간결하게
  • 메서드의 파라미터를 type명과 변수명을 적고 간략하게 설명
  • 리턴 변수, 예외사항 설명
/**
* 메서드의 기능을 설명 중이다.. 간략하게 적을 것.
* 
* @ param int a 메서드의 파라미터 설명
* @ return 반환하는 것 설명
* @ exception 예외사항
*/

기타 주석처리

  • 코드 내부의 짧은 주석은 // ...로 표기
  • 코드가 산만하지 않게 주석을 멀리 사용
  • 특별한 경우를 제외하고는 주석을 사용하지 않는다.
  • 의문점이나 해결못한 것은 임시주석 사용 /* ... */

구현 주석

block 주석

  • 파일, 메서드, 자료구조, 알고리즘의 설명 제공
  • 파일의 시작이나 메서드 전에 사용
  • 수정할 일이 없는 특별한 주석은 /*- ... */로 표기
  • 코드의 나머지로부터 분리하기 위해 처음 한 줄은 비워둔다.
/*
* 여기에 block 주석 작성
*/

/*-
* 특별한 경우의 주석
* 얘는 잘 모르겠다.
*/

single line 주석

  • 짧은 주석은 뒤에 따라ㅜ 오는 코드와 같은 레벨의 들여쓰기
  • 한 줄로 써지지 않는다면 block 사용
while(true){
	/* single line 주석 */
   	...
}

trailing 주석

  • 매우 짧은 경우 코드와 같은 줄에 작성
  • 코드와의 확실한 구별을 위해 충분히 멀리 떨어뜨림
if(...){				/* trailing */
	...
}

end of line 주석

  • 한줄 모두를 주석처리 하거나 일부분을 주석처리할 때 사용
  • 여러 줄에 연속되어 사용은 피할 것
  • 코드를 주석처리할 때는 여러 줄을 연속 사용
if(...){				// end of line
	...
}

// 블럭을 통채로 주석처리
// int a = 0;
// print a;
// a = 1;

javadoc verbos author version d <directory> <java source> 명령어 작성 시 HTML 문서 형태로 클래스의 API를 문서화 한다.

참고자료

All of Software
Rough Existence