Clean Code "주석"

Clean Code "주석"

Clean Code 저서를 읽은 후 주관적인 내용을 많이 포함하고 있는 글이기 때문에 틀린 내용이나 생각이 다른 부분이 있다면 제안해주세요 :)

 

 

우리는 나쁜 주석과 좋은 주석을 짚어보기 전에 분명히 해야 할 것이 있다.

바로 가장 좋은 코드 구성은 주석을 달지 않는 것이라는 점이다. Clean Code 저서에서는 주석을 필요악이라고도 표현한다.

코드는 리팩토링을 거쳐 변화하고 진화하지만 주석은 유지 보수되지 않는다. 따라서 정말 필요한 주석만을 추가하고 필요성이 없어진 주석은 없애주어야 한다.

다시 한 번 명심하자. 주석을 사용할 바에 코드로 그 의도를 표현하자.

 

 

좋은 주석

 

법적인 주석

오픈소스를 사용할 경우 소스코드 상단에 저작권을 표시하는 주석을 추가하는 것은 좋은 주석이라기 보단 필수에 가깝다.

오픈소스 가이드에서도 저작권 표시를 위해 주석을 포함할 것을 고지하고 있다.

 

의미를 명료하게 밝히는 주석

써드파티 라이브러리 등을 사용할 때면 인수, 반환 값을 커스텀하기 어렵기 때문에 그 의미를 명확하게 하기 위한 주석을 추가해주는 것이 도움이 될 수 있다.

여기서 주의할 점은 주석이 올바른지 검증하기 쉽지 않다는 것이다. (IDE의 도움도 받기 힘들다.) 따라서 정확한 의미를 포함한 주석을 달았는지 각별한 확인이 필요하다.

 

TODO 주석

TODO 주석은 앞으로 진행할 작업에 표시를 해두기에 적합할 것이다.

또 많은 IDE에서는 TODO 주석을 찾아주는 기능을 제공하기도 한다. 그중에서도 VSCode에서 유용하게 사용할만한 주석 관련 Extension을 소개해보고자 한다.

TODO Tree

"TODO Tree"는 VSCode에서 'TODO', 'FIXME' 주석을 단 코드의 위치를 자동으로 탐색해주는 유용한 확장 앱이다.

// TODO : 할일 리스트 1
// FIXME : 학생 검색 관련 쿼리 수정하기

위와 같이 TODO, FIXME 주석을 달아주게 되면, VSCode 사이드바의 나무 모양 아이콘을 통해 프로젝트 내의 모든 TODO, FIXME 주석들을 자동 탐색해준다.

코드에서 또한 다음과 같이 눈에 띄게 표시되기 때문에 우리는 TODO 주석을 더 효율적으로 탐색할 수 있다. 더불어 setting.json에 코드를 추가하면 주석 글자 색이나 아이콘 커스텀이 가능하기 때문에 자세한 내용은 Extension Overview를 참고한다.

 

Better Comments

Better Comments Extension 또한 주석에 다양한 태그로 그 의미를 표시하기에 용이하다.

설치 시 디폴트로 위와 같은 태그가 설정되어 있다. 본 확장 앱 또한 setting.json에서 다양한 커스텀이 가능하기에 필요시 개인에 맞춤화된 설정값들을 지정해보는 것도 좋은 방법일 듯하다.

 

주석을 대체할 수 있는 코드를 짜는 것이 베스트이지만, 위와 같이 때로는 주석을 포함하면 더 나은 코드를 구성할 수도 있다. 그렇지만 주석은 언제나 다시 필요가 없어질 수도 있고 잘못된 의미로 받아들여질 수 있으니 필요 없는 주석은 제 때 지우고 기존 주석의 의미를 신경 써야 한다

 

 

나쁜 주석

있으나 마나 한 주석

export const enrollItemAPI = async (payload) => {
  //물품 등록 api
  try {
    const response = await axios.post("/api/saleItem/enrollItem", payload, {
      headers: {
        "Content-type": "multipart/form-data",
        Accept: "application/json",
      },
    });
    return response.data;
  } catch (e) {
    console.error(e);
  }
};

한 프로젝트에서 직접 달아두었던 주석을 발췌해보았다. 당시 무슨 생각으로 이런 주석을 남겼는지는 의문이지만 있으나 마나 한 주석으로 보여진다.

우리는 함수명만으로도 물품을 등록하는 API 코드라는 것을 알 수 있다. 너무나 당연한 사실을 언급하는 주석은 달지 않는 것을 권유한다.

 

닫는 괄호에 다는 주석

우리는 때로 중첩이 심한 함수에서 닫는 괄호에 주석을 함께 적어주는 코드를 본 적 있을 것이다.

하지만 이런 코드에서 주석이 가독성을 높여주지는 않는다. 또 중첩이 심한 함수는 되도록 구성하지 않는 것이 바람직하다.

그래서 닫는 괄호에 주석을 달기보단 함수 중첩을 없앨 수 있는 방법을 먼저 모색하는 것이 좋다.

 

저자를 표시하는 주석

때때로 소스코드에 저자를 표시하는 경우가 있다. 아마 해당 코드에 대해서 누구에게 물어봐야 할지 정보를 남겨두었을 것이다.

하지만 저자 확인과 같은 기능들은 GitLens와 같은 확장 앱을 활용할 수 있으니 필요 없는 주석은 가급적 추가하지 말자.

 

주석으로 처리한 코드

가장 필요 없는 주석에 해당하지 않나 생각한다.

주석으로 처리된 코드는 심지어 다른 개발자들이 필요한 코드인가 싶어 지우기도 어려워진다. 모든 소스 코드는 Git과 같은 형상관리 툴이 제어해주기 때문에 특히! 코드를 주석으로 남기지 말자.