TIL.14 | 주석 효과적으로 달기

원용현·2023년 6월 5일

TIL

목록 보기

14/18

주석

해당 코드를 읽을 사람의 편의를 위해 코드에 추가되는 간단한 설명을 의미한다.

주석으로 작성되는 부분은 컴파일에서는 미비할 정도의 컴파일 속도에 영향을 줄 수 있지만, 빌드 시에는 주석이 모두 제거되고 빌드되기 때문에 실제 실행파일을 실행할 때는 주석이 프로그램의 속도에 영향을 끼치지 않는다.

이런 주석을 잘 활용하면 코드를 작성하는데 생산성과 가독성을 높이는데 여러 도움을 얻을 수 있다.

대충 쓰면 안될까?

코드 내에서 // ... 또는 /* ... */ 로 작성되는 주석은 개발자가 작성된 코드에 대해서 코멘트를 남길 때 사용한다. 이런 주석은 무조건 많이 남기면 좋을 것 같지만 무조건 그렇지는 않다.

적절한 주석의 양

주석은 코드를 읽는 사람, 즉 나 뿐만 아니라 다른 사람까지 배려해서 작성을 해야한다. 내 주석을 읽을 사람이 필요한 정보를 적절하게 제공할 수 있어야 하는데 어느 정도의 정보를 제공해야할지 결정하는 것은 어렵다. 너무 적은 주석은 불친절하고 너무 많은 주석은 과도하다. 너무 적은 주석은 해당 코드가 무엇을 의미하는지 알아보기 어렵고, 너무 많은 주석은 코드의 가독성을 떨어뜨리고 주석을 작성하는데 비용(시간)을 많이 투자하게 된다.

주석의 형식

하나의 프로젝트에서 두 개의 다른 파일의 주석 형식이 다르면 딱히 문제될 것이 없겠지만 10개, 100개, 파일의 양이 많아지면 많아질수록 서로 다른 주석의 형식은 코드를 읽는 가독성을 떨어뜨리고 오히려 주석이 코드를 방해하는 문제를 가져온다.

좋은 주석이란?

주석의 표준

주석을 작성하는 방식에 대한 표준을 정해놓고 해당 프로젝트에 참여하는 사람이 모두 같은 표준을 사용하도록 한다. 이것에 대해서 매 프로젝트마다 다른 표준을 가지고 있다면 다른 프로젝트에 참여할 때마다 해당 표준에 대해서 공부하기보다는 모든 사람이 표준으로 삼고있는 것을 채택하여 사용한다.

언어마다 다른 주석 표준을 가지겠지만 대표적으로 JavaDoc, JSDoc 등이 있다.

소스코드보다 주석을 먼저 작성해보자.

코드를 작성하면서 주석을 달기보다는 함수를 생성하기 전에 해당 함수에 대한 설명을 먼저 주석으로 만들어보자. 많은 학생들이나 개발자들도 코드 작성이 끝나면 주석을 다는 습관이 있을텐데, 함수를 생성하기 전에 먼저 주석으로 함수의 핵심내용을 담아놓으면 코드의 수정이 어려번 발생해도 주석을 수정하는 경우는 많이 없을 것이다.

function 위주로 주석을 달아보자.

모든 코드에 주석을 다는 것은 미친 짓이고 시간 낭비이다. 그렇기 때문에 효율적으로 주석을 달아야하는데 여러가지 선언한 변수, 담고있는 코드의 알고리즘, 반환할 내용 등 가장 큰 범위에서 주석을 달았을 때 가장 효율적인 것은 함수라고 생각한다.

주석 처리 방법

한 줄 주석

원하는 부분만 주석처리하기 위해서 사용한다. 처리하는 방법은 // ... 으로 작성한다.

// number 타입 인자 두 개를 입력받아 덧셈 후 결과를 반환하는 함수
const add = (a:number, b:number) => {
	return a + b
}

위와 같이 원하는 줄을 주석으로 처리하고 싶을 때 //를 가장 앞에 작성하여 사용한다. // 가 입력되면 Enter를 통한 줄바꿈이 일어나기 전까지 존재하는 모든 문자에 대해서 주석처리가 들어간다.

전체 주석

보통 /* ... */ 을 통해서 구현한다. /* 으로 열고 */ 으로 닫기 전까지 그 사이에 존재하는 모든 문자에 대해서 주석처리가 들어간다.

/* number 타입 인자 두 개를 입력받아 덧셈 후 결과를 반환하는 함수 */
const add = (a:number, b:number) => {
	return a + b
}

/* ... */ 의 경우에는 한 줄을 주석처리 하기보다는 여러 줄을 한 번에 주석처리 하기위해서 보통 많이 사용된다.

/* 
 number 타입 인자 두 개를 입력,
 덧셈 후 결과를 반환하는 함수 
 */
const add = (a:number, b:number) => {
	return a + b
}

위와 같이도 사용되지만 조금 더 주석의 가독성을 높이기 위해서 다음과 같이 사용되기도 한다.

/* 
 * number 타입 인자 두 개를 입력,
 * 덧셈 후 결과를 반환하는 함수 
 */
const add = (a:number, b:number) => {
	return a + b
}

문서화 주석

위의 내용으로 주석에 대한 전반적인 내용을 알 수 있었다면 아래부터는 조금 더 심화된 내용을 알아보려고한다.

js에서는 함수를 호출할 때 js 자체에서 제공하는 함수를 사용하면 해당 함수에 들어갈 parameter의 개수와 종류, 이름 등을 알려주는 툴팁을 제공하는데 이것을 내가 만들어낸 함수에서도 제공하도록 만들 수 있다.

즉 만들어낸 함수에 대해서 주석을 달아 문서화를 해놓으면 해당 함수를 호출할 때 자동완성에 대한 툴팁을 제공하도록 한다.

방법은 /** ... */ 을 사용하는 것이다. 위의 전체 주석과 같이 열고 닫는 사이의 모든 문자들이 주석처리되는데 이 내용을 함수를 선언하는 위에 작성하면 해당 함수를 호출할 때 주석의 내용이 함께 툴팁으로 제공된다.

사용할 때 다음과 같이 뺄셈을 하는 함수를 선언한다.

선언된 함수의 바로 위에 /** 을 입력하면 자동 완성이 출력되는데 /** */을 실행하면 다음과 같이 문서화 주석이 완성된다.

위에서 부터 차례대로 빈 곳을 채워주면 다음과 같이 나타낼 수 있다.

주석의 가장 위에는 해당 함수에 대한 간단한 설명을 작성한다.
@param {*} a ...
{ } 사이에는 해당 파라미터에 대한 type을 지정하고 파라미터 뒤에 한 칸을 띄고 해당 파라미터에 대한 설명을 작성한다.
@returns
함수의 실행 결과 반환될 값에 대한 설명을 작성한다.

이제 새로 만들어진 함수에 문서화 주석까지 끝마쳤다면 해당 함수를 호출하여 사용하게 될 경우 다음과 같은 툴팁이 함수에 대한 설명으로 제공된다.