더 나은 코드 주석을 위한 13가지 팁

어려운 코드를 짜기위한 기술인 리펑토링에 보면 그 특징 중 하나로 "명백한 사실을 상세히 설명하기"라는 항목이 있다. 너무 자세한 코드에 대한 주석은 코드의 가독성을 떨어뜨리는 원인이 되곤하지만, 그렇다고 주석을 안달수는 없는 일이다.

주석의 목적은 코드의 가독성을 높이는 것이다. 코드에 주석을 다는 일이 쉬워보이기는 하지만 막상 자신이 주석을 달아놓고도 이해하지 못하는 경우가 생긴다.

"13 Tips to Comment Your Code"라는 글이 있어서 간단히 정리해본다.


1. 각각의 레벨에 주석을 달아라.

클래스에는 간단한 설명과 함께 작성자와 마지막으로 수정된 날짜를 적는다.
각각의 메소드에는 사용 목적, 기능, 파라미터와 리턴값에 대한 설명을 적는다.

-> 객체지향 언어가 아닌 C 같은 경우라면 각각의 파일과 함수에 같은 방식을 적용하면 되겠다.
-> 개인적으로 날짜를 적는 건 그리 소용이 없는 것 같다. 코드를 고치면 자동으로 수정된 날짜가 바뀌는 것이면 모를까, 고칠때마다 일일이 고쳐주는 건 조금 낭비가 아닐까 싶다.

2. 단락(paragraphs)별 주석을 이용하라.

코드 블록을 하나의 일을 하는 단락으로 나누고 어떤 처리를 하는지 적어둔다.

-> 1번 내용과 거의 비슷하다.

3. 연속되는 코드 라인에 있는 주석을 정렬하라.

const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F; // mask bit TCP

이렇게 되어 있는 주석보다는

const MAX_ITEMS = 10; // maximum number of packets
const MASK = 0x1F;       // mask bit TCP

이런 식으로 되어 있는 것이 읽기에 더 좋다.
어떤 개발자는 탭을 이용하여 정렬하고, 어떤 개발자는 스페이스바를 이용하여 정렬한다.
에디터나 IDE 마다 (또는 개발자마다) 탭 간격이 다르기 때문에 스페이스바를 이용하는 것을 추천한다.

4. 읽는 사람의 지능을 무시하지 마라.

if (a == 5)         // if a equals 5
    counter = 0;  // set the counter to zero

이건 좀 곤란하다.-_-

 

반응형

5. 예의를 갖추어라.

"어떤 멍청한 사용자가 음수를 입력할 경우의 처리"라던가, "처음 개발자의 서투른 구현에 따른 버그를 수정하였음" 같은 (설마 이런 주석을 누가 달까 싶지만) 무례한 주석은 피하라.
나중에 누군가 (사장님이나 고객 또는 서투른 구현을 한 처음 개발자) 그 주석을 읽게 될지도 모른다.

-> 개인적으로 "왜 이딴식으로 짜놓은거야"라는 주석까지는 본 적이 있다. (다행히(?) paromix군이 짠 코드는 아니었지만^^)

6. 요점만 언급하라.

아이디어를 전달하기 위한 내용만 적어라. 아스키(ASCII) 그림이나 농담, 시 같은 것들은 주석으로 적을 필요가 없다.
주석은 간단하고 핵심만 전달하면 된다.

7. 일관된 양식을 사용하라.

코드와 주석을 읽게될 다른 개발자를 위하여 일관된 주석 양식을 사용하라.

-> 나중에 주석을 이용하여 수정된 코드를 추적해 나갈 때, 일관된 방식이 있다면 좀 더 수윌하다.

8. 내부적인 목적을 위한 태그를 사용하라.

팀으로 코드를 개발하고 있다면, 프로그래머간에 원활한 의사소통을 위하여 일관된 태그 집합을 도입하라. 예를들어 추가 구현사항이 필요한 경우 "TODO:" 태그를 이용할 수 있다.

int Estimate(int x, int y)
{
    // TODO: implement the calculations
    return 0;
}

-> TODO 태그보니까 생각나는데, MS쪽은 TODO 태그를 좋아하는 것 같고 Sun 쪽은 FIXME 태그를 좋아하는 것 같다. 사실 여부는 보증할 수 없지만.^^

9. 코드를 작성하는 동안 주석을 달아라.

코드를 작성하는 동안 코드의 내용이 머리속에 정확히 그려져 있을 때 주석을 추가하라. 코드 작성을 마치고 주석을 달려고하면 시간이 두배는 더 걸릴 것이다. "주석을 달 시간이 없어요", "전 지금 바빠요", "프로젝트 일정이 밀렸어요"와 같은 변명은 통하지 않는다. 코드를 작성하기 전에 주석 먼저 써놓는 것도 효과적이다.

-> 의외로 코드 작성을 마치고 주석을 달려고 하는 사람들이 많다. 그리고 코드 작성을 마치면 대부분 주석을 달다가 포기하고 만다.

10. 스스로를 위한 것이라고 생각하며 주석을 달아라. (사실 스스로를 위한 것이기도 하다)

결과적으로 주석으로 인한 이득(또는 피해)을 가장 먼저 보는 사람은 바로 코드 작성자 자신이다.

11. 코드를 갱신하면 주석도 갱신하라.

코드와 주석의 내용이 맞지 않는다면, 주석은 없는 것만 못하다. 코드와 주석은 함께 변화해야 한다. 리팩토링 툴을 이용하여 리팩토링을 진행할 경우에 코드는 변경되면서 주석은 변화하지 않는 경우가 발생하므로 특히 주의하라.

12. 주석의 황금 규칙 : 읽기 쉬운 코드

많은 개발자들을 위한 기본 원리 중 하나는 "코드 스스로 말하게 하라"이다. 비록 이 규칙이 주석 달기를 귀찮아하는 프로그래머에게 변명거리를 제공하고 있기는 하지만, 자명하게 짠 코드는 주석이 없어도 이해하기 쉽다.

13. 이 팁들을 동료들과 공유하라.

10번 팁에서 좋은 주석이 스스로에게 도움이 된다고 말하긴 했지만, 여기 소개한 팁들은 함께 일하는 팀원들을 포함하여 모든 개발자들에게 이득이 될 것이다. 이해와 유지보수가 쉬운 코드를 위하여 여기에 있는 팁을 공유하라.

출처 : http://www.devtopics.com/13-tips-to-comment-your-code/