[Clean Code][TIL] 주석

게시 2024/08/28 업데이트 2024/08/28

By mgcllee

이 포스트는 로버트 C.마틴의 Clean Code 속 4장(68p ~ 94p) 내용에 대한 후기입니다.

“나쁜 코드에 주석을 달지 마라. 새로 짜라.” (4장 68p)

주석 말고 코드로 의도를 표현할 것

위키백과에서는 주석을 다음과 같이 설명하였습니다.
“소스 코드를 더 쉽게 이해할 수 있게 만드는 것이 주 목적이며, 협업할 때 유용히 쓰인다.”
이 설명처럼 주석은 코드에 대한 추가적인 설명입니다.
명료한 이름으로 작성된 코드는 이름만으로 설명이 가능하기 때문에
아래와 같이 몇 가지 특수한 주석을 제외하면 코드를 명료한 이름으로 수정하는 것이 좋습니다.

좋은 주석

법적인 주석

  
////////////////////////////////////////////////////////////
//
// SFML - Simple and Fast Multimedia Library
// Copyright (C) 2007-2024 Laurent Gomila (laurent@sfml-dev.org)
//
// ...

위 주석은 SFML의 Main.hpp 파일의 첫 부분입니다.
주석의 내용처럼 법적 권리 표기는 좋은 주석 이전에 필요하고 타당한 주석입니다.

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

  
assertTrue(A.compare(A) == 0); // A == A
assertTrue(A.compare(B) != 0); // A != B
assertTrue(A.compare(B) == -1);// A < B

인수 혹은 반환값이 STL처럼 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석은 유용합니다.
그러나 작성한 주석이 옳바른지 검증하기란 어렵습니다.
따라서 주석을 작성하기 전 더 나은 방법이 없는지 고민하고
작성한다면 정확한 내용을 전달할 수 있도록 해야합니다.

TODO 주석

프로그래머가 필요하지만 당장 구현하기 어려운 업무를 TODO 주석에 기술합니다.
여기서 대다수의 IDE는 TODO 주석 전부를 찾아 보여주는 기능을 제공하므로
필요한 곳 마다 작성할 수 있지만 나쁜 코드를 남겨 놓는 핑계가 되어선 안됩니다.

Visual Studio 2022 에서는 위의 사진처럼 주석에 TODO 라고 작성한 뒤
Task List 라는 뷰를 열면 한 번에 모아서 볼 수 있습니다.
이때 기본으로 등록된 TODO 키워드는 대소문자를 구분하지 않지만 반드시 붙여서 사용해야 합니다.
만약, 새로운 키워드를 등록하려면 Tools -> Options -> Environmment -> Task List 를 편집하면 됩니다.

위의 여러 주석 외에 정보를 제공하는 주석, 의도를 설명하는 주석,
결과를 경고하는 주석, 중요성을 강조하는 주석 등 여러 주석이 있지만
가장 좋은 주석은 주석을 달지 않는 방법을 찾아낸 주석 입니다.

나쁜 주석

같은 이야기를 반복하는 주석

코드에서 충분한 정보를 제공했지만 주석으로 동일한 정보를 제공한다면
코드를 읽는데 방해만 될 뿐 전혀 도움이 되지 않습니다.

  
// 사람이 읽을 수 있는 이름
string name;

// Pipeline 객체
Pipeline pipeline = new Pipeline();

이력을 기록하는 주석

Git을 사용한다면 제거 대상 1순위 주석입니다.
소스 코드 관리를 주석으로 하게 된다면 코드가 오래될수록
기록의 양이 거대해져 파일 자체가 커질 수 있기 때문입니다.

주석으로 처리한 코드

이력 기록 주석과 같이 소스 코드 관리 시스템을 사용한다면
주석으로 만들 것이 아니라 제거하여 시스템에 등록하면 문제가 해결됩니다.

전역 정보

주석을 달아야 한다면 근처에 있는 코드만 기술해야 합니다.
코드 중간에 전역 변수와 관련된 주석을 작성했을 때,
해당 전역 변수가 수정된다면 더 이상 그 주석은 유효하지 않기 때문입니다.

모호한 관계

주석은 작성한 프로그래머만 아니라 코드를 함께 작성하는 다른 팀원도 읽을 수 있습니다.
이때, 작성한 주석이 코드와 무슨 관계가 있는지 파악하기 어렵다면
그 주석에 대한 설명하는 주석(주석에 대한 주석)을 작성해야 될 수 있습니다.
아래는 한 줄의 코드를 설명하기 위해 여러 주석을 작성했지만 여전히 이해할 수 없는 코드입니다.

  
/*
* 모든 픽셀을 담을 만큼 충분한 배열로 시작합니다. (여기에 필터 바이트를 더합니다.)
* 그리고 헤더 정보를 위해 200 바이트를 더합니다.
*/
auto pngBytes = new char[((this.width + 1) * this.height * 3) + 200];

위의 주석 외에도 대다수의 주석 이 나쁜 주석에 속합니다.