728x90

일관성
코멘트도 일관성을 유지하는 것이 좋다. 보기 좋은 떡을 만들라. 누가 뭐래도 코멘트는 사람에게 보여주기 위해 작성하는 것이 아닌가!

뚜렷한 블록 코멘트
에디터에서 색이 다르고 굵게 표시되는 경우가 많지만 흑백으로 프린트해서 봐야 할 수도 있다.(특수한 경우를 생각하지 말고 일반적인 것을 생각하라!)
코멘트의 시작과 끝은 들여쓰기 등으로 다른부분과 구분을 지어야 한다.

/*
  * 좋은 예시의
  * 블록 코멘트
  * 알아보기가 쉽다.
*/

/* 나쁜 예시의
          블록 코멘트
알아보기 어렵다.
*/


1행 코멘트
코드 중간에 들어가지 않도록 해야 한다. 만약 코드 중간에 한줄을 잡는다면
코드의 들여쓰기와 맞춰 알아보기 쉽도록 해야한다.
행 끝에 따로 띄어서 코멘트를 작성하는 것도 괜찮다.
오른쪽에 코드로부터 분리하여 코멘트들을 작성하는 것인데 알아보기는 쉬우나 코드를 수정할 때 간격을 다시 맞춰야 하고 코드가 긴 행을 만나면 화면 밖으로 나가버릴 가능성도 있다.

일반적인 약속(관례)
코멘트는 코드의 위쪽에 쓰인다. 즉, 코멘트가 먼저 나오고 그에 해당하는 코드가 나온다.
코멘트가 단락의 시작으로 여겨지도록 한다.

유지보수가 저렴한 스타일을 선택
/***********************************
*******     모양은 이쁘지만    ********
*******  간격맞추기가 어렵다  ********
***********************************/

게다가 스페이스를 사용하느냐 탭을 사용하느냐에 따라 모양이 다르고 탭을 사용하는 경우 탭의 너비설정이 다르면 또 모양이 달라진다. 쓸데없는 곳에 열정을 낭비하지 말자.

방파제 코멘트
가끔 코멘트가 코드 사이에 방파제 역할을 하는 경우가 있다.
프로그래머는 중요한 코멘트를 특별하게 표시할 필요가 있는데 한 소스파일 안에 여러개의 클래스가 구현되어 있는 경우, 중요 섹션을 구분하기 위해 방파제 코멘트를 사용한다.
/***********************************
* 방파제 코멘트
* 가끔 필요할 때가 있다
***********************************/

좀 전에 함부로 사용하지 말라고 한 것과 비슷한 모양이지만 눈에 띄는 것이 중요하지 ASCII예술을 통해 이쁘게 하지 마라. (ASCII예술이란 특정한 상황에서 띄어쓰기 등으로 화면에 보이는 것을 미술적으로 표현하는 것을 말하는 듯하다.)

플래그
다른 사람의 코멘트를 읽을 때 약속된 플래그를 알아두는 것이 좋다.
// XXX      : 문제를 일으키는 코드나 재작업이 필요하다는 표시
// FIXME   : 고장 난 부분
// TODO    : 누락된 기능(나중에 돌아왔을 때 추가해야 할 기능)
TODO를 사용하기 보다는 exception을 던지는 것이 훨씬 매끄럽다. 하지만 다른 사람이 해놓은 것을 알아볼 필요는 있겠지.
하지만 플레그를 두려워 하지 마라. 코드를 마무리하기 전에 플레그를 검색해보면 된다.

파일헤더 코멘트
앞에서도 이야기 했던 내용이다. 모든 소스 파일에는 헤더 코멘트로 시작해야 한다.

불필요한 코멘트
코드를 수정할 때 코멘트를 달지마라.
어떠한 내용을 무엇때문에 어떻게 고쳤다..라고 코멘트를 다는 것은 불필요하며 지저분하다. 필요한 경우 결함 추적 시스템(fault-tracking system)을 이용해 결함을 찾고, 파일의 예전 리비전을 끄집어내어 조사할 수 있다. 이러한 불필요한 코멘트는 오히려 코드를 어지럽힌다.

코멘트 유지보수
바로 위에서 코드를 수정할 때 코멘트를 달지 말라고 했다. 그렇다면 코드를 수정할 때는 그냥 넘어가면 되는 것인가? 절대 아니다.
코드를 수정할 경우 그와 관련된 코멘트를 모두 확인하고 보수해야 한다.

코멘트를 의심하라
코드를 코멘트로 막아두는 경우가 있다. 일시적인 경우지만 때로는 오래갈 때도 있다. 이런 경우 적당한 설명을 함께 두거나 아예 코드 자체를 지워야 한다.
코멘트가 있더라도 코드의 수정과 함께 유지보수가 되지 않은 코멘트일 수 있고 작성한 사람이 잘못 작성했을 가능성도 있다. 항상 코드를 신뢰하고 코멘트는 의심해야 한다.


-----------정리-------------
* 소량의 코멘트를 작성하라
* 왜(why)에 대해 작성하라
* 코멘트보다 코드의 작성에 집중하라
* 코드와 함께 유지보수하라
& 코드의 내용을 중복하지 마라
& 자신만 알아보는 코멘트를 작성하지 마라

728x90

+ Recent posts