Eojin Han

핵심 주석은 필요 시에만 남긴다. 코드로 의도를 표현하자.주석은 실제와 다를 수 있다.주석은 나쁜 코드를 보완하지 못한다.좋은 주석 법적인 주석 정보를 제공하는 주석 의도를 설명하는 주석 결과를 경고하는 주석 ToDo 주석 공개 API 의 경우 docs 중요성을 강조하는 주석 나쁜 주석 주절거리는 주석 ( 정보가 부족한 주석 )같은 이야기를 반복하는 주석 ( 쓸모 없는 이야기를 하는 주석 )오해할 여지가 있는 주석 ( 명확하지 않은, 약간의 잘못된 정보를 포함 )이력을 기록하는 주석 있으나 마나 한 주석 함수나 변수로 표현할 수 있다면 코드로 표현해라 위치를 표현하는 코드 닫는 괄호에 주석 달기 공로를 돌리거나 저자를 표시하는 주석 주석으로 처리된 코드 전역 정보 너무 많은 정보 모호한 관계 비공개 코드인데 docs를 남기는 경우

핵심

주석은 필요 시에만 남긴다. 코드로 의도를 표현하자.

사실 코드만으로 내용이 충분히 전달된다면 굳이 주석을 남길 필요가 없는데, 코드로 충분히 잘 표현하지 못해서 부연설명을 남기는 것이다.

깔끔한 코드로 충분히 커버할 수 있다면 주석을 지우고 코드를 고치는 것이 훨씬 좋다.

주석은 실제와 다를 수 있다.

⚠️

주석은 거짓말 할 수 있다.

주석은 실제 코드의 동작과 다르게 서술할 수 있어서 무조건 맹신해서는 안된다.

부정확한 주석은 없는 것보다 안좋다.

최대한 코드로 어떻게 표현할 지를 더 많이 고민하고, 주석 대신 코드를 통해 이해할 수 있도록 노력해야 한다.

주석은 나쁜 코드를 보완하지 못한다.

코드로 충분히 표현하지 못하였거나, 코드가 지저분하거나 등의 이유로 주석을 적어야겠다는 생각을 하게 된다.

주석을 달아야겠다가 아니라 코드를 고쳐봐야겠다가 되어야 한다.

지저분한 코드에 주석을 단다면 부연설명으로 이해를 도울진 몰라도 주석을 쓴다고 안좋은 코드가 잘 읽히진 않는다. 주석이 없더라도 깔끔하게 잘 정리된 코드가 훨씬 읽기도, 이해하기도 좋다.

좋은 주석

법적인 주석

저작권 정보, 소유권 정보 등을 주석으로 명시하는 것은 충분히 의미있다.

정보를 제공하는 주석

때로는 기본적인 정보를 주석으로 남기면 도움이 되기도 한다.

⚠️

그래도 이 정보를 코드에 녹일 수 있으면 코드로 적는 쪽으로 변경할 것을 권장함


// 테스트 중인 Responder 인스턴스를 반환한다.
protected abstract Responder responderInstance();

// 그런데 이것을 아래와 같이 고친다면 주석 없이도 충분히 표현할 수 있으므로, 코드에 녹이는 것이 더 좋다.
// responderInstance -> responderBeingTested 으로 네이밍 변경

의도를 설명하는 주석

ex) 정렬(sort) 알고리즘을 합의된 비지니스 로직대로 구현하였을 때, 합의된 비지니스 로직에 대한 설명과 결정배경을 주석으로 달아두면 왜 이런 방식으로 정렬을 해야하는지에 대한 맥락정보를 제공하여 이해를 도울 수 있다.

로직은 코드로 단번에 이해될 지라도, 왜 이렇게 했을까? 하는 의문이 들 수 있는 부분을 해소시켜주는 관점으로 이해하면 좋다.

결과를 경고하는 주석

@@한 상황에서는 실행하면 안된다 등의 정보 + 이유 설명

ToDo 주석

앞으로 할 일, 해야할 일을 명시함.

공개 API 의 경우 docs

중요성을 강조하는 주석

대수롭지 않다고 느낄 수 있는 부분을 강조하는 목적으로 쓰는 주석도 의미가 있다.

코드를 수정하거나 리팩토링 하는 경우에도 신경쓰며 고치게 된다.

나쁜 주석

주절거리는 주석 ( 정보가 부족한 주석 )

코드를 작성한 사람에게는 도움이 될 지라도, 다른 개발자는 쉽게 이해할 수 없는 주석

같은 이야기를 반복하는 주석 ( 쓸모 없는 이야기를 하는 주석 )

주석이 있다면 읽으려고 하게 되는데, 중복된 내용을 반복해서 주석으로 남기면 읽는 시간을 낭비시킨다.

오해할 여지가 있는 주석 ( 명확하지 않은, 약간의 잘못된 정보를 포함 )

이력을 기록하는 주석

지금까지 변경된 이력을 주석으로 남기는 것이 무슨 의미가 있는가?

깃 이력을 통해서 충분히 과거의 코드와 변동내역을 확인할 수 있고, 중요한 것은 현재의 코드가 어떻게 되어있는지에 대한 내용이다.

있으나 마나 한 주석

주석을 굳이 안읽어도 알 수 있는 너무나 당연한 주석

ex) constructor() // 이 코드는 생성자 코드이다.

ex) const Month // ‘월’에 대한 정보를 담는 변수다.

⚠️

지나친 참견이 반복된다면 점차 주석을 읽지 않게 되고, 의미있는 주석조차 놓칠 수 있다.

함수나 변수로 표현할 수 있다면 코드로 표현해라

함수 또는 변수로 코드를 잘 나누는 것만으로도 충분히 설명이 되는 내용이라면, 주석을 없애고 코드로 표현하자.

위치를 표현하는 코드

이런 주석은 드물게 유의미한 의미를 주기도 한다.

하지만 필요한 순간에 충분한 주의를 집중시킬 수 있으려면 이러한 주석을 불필요하게 남발하지 않아야 한다.


// 변수 선언부
const a = 'a';
const b = 'b';
...

// 함수 선언부
const func1 = ()=>{};
const func2 = ()=>{};

...

// 렌더
return (
	<>
		{...}
	</>
)

닫는 괄호에 주석 달기

어떤 블럭이 닫힌 건지를 표현하기 위해, 닫히는 괄호에 주석으로 어떤 블럭인지 내용을 표시하는 경우가 있다.

코드가 엄청나게 길다면 의미가 있는 정보일 수 있지만, 이러한 상황이라면 로직을 깔끔하게 나누는 것이 더 바람직하다.


try{
...
...
...
...
...
...
...
} // try 블럭이 닫힌 것임

switch(a){
 case 'a': ... break;
 case 'b': ... break;
 case 'c': ... break;
 case 'd': ... break;
...
...
...

} // switch 구문이 닫힌 것임

공로를 돌리거나 저자를 표시하는 주석

소스코드 관리 시스템을 통해 충분히 알 수 있는 내용이다.


// @@님이 추가한 코드
// **님이 리팩토링 하였음
// ##님이 성능 최적화까지 해둠

주석으로 처리된 코드

안쓰는 코드여서 주석처리를 해두면, 다른 개발자들이 봤을 땐 이유가 있어서 남겨둔 것이라고 생각하고 쉽게 삭제 결정을 내리지 못한다.

일시적으로 기능을 막아두는 등 의미가 있는 게 아니라, 단순히 안써서 주석처리를 하는 경우에는 그냥 코드를 지워라.

전역 정보

주석은 근처에 있는 코드에 관한 정보만 담는 것이 더 좋다.

웬만하면 시스템 전반적인 정보를 기술하지 마라

포트에 기본값을 주는 부분은 이 코드에는 전혀 없는데, 여기서 다른데서 구현된 코드에 대한 내용을 적는 것은 좋지 않다.

정보가 중복될 뿐더러, 실제로 기본값을 설정하는 코드가 다른 값으로 변경되었을 때 해당 주석도 같이 변경되어야 하는데 놓치는 경우가 대부분일 것이고, 그러면 주석은 잘못된 정보를 전달하는 꼴이 된다.

너무 많은 정보

필요 이상의 불필요한 역사나, 장황한 부연설명은 오히려 필요한 정보를 흐리게 된다.

base64 인코드/디코드 모듈에선 RFC 2045에 의거한다는 정보만 주어도 충분하다.

모호한 관계

기왕 주석을 통해 부연설명을 하기로 했으면, 독자가 충분히 단번에 알아들을 수 있도록 명확하게 적어야 한다.

주석을 읽고 다시 질문을 하게 된다면 주석을 잘못 남긴 것이다.

주석을 남겨놓았으나, 필터 바이트에 대한 정보가 없다. 필터 바이트가 뭐야? 라고 질문을 하게 되므로 잘못된 주석임을 알 수 있다. 심지어 필터 바이트가 아래 식에서 어떤 영향을 끼치는 건지도 유추하기 어렵다.

비공개 코드인데 docs를 남기는 경우

공개 API 라면 docs가 유용한 정보가 되지만, 내부에서만 쓰이는 경우에는 불필요한 정보일 뿐이다.

docs를 더 산만하게 만든다.

좋은 주석을 남기자

핵심