내 맘대로 블로그

주석 작성은 개발보다는 문서 작성에 가까운 일.

고로, 개발자에게 가장 인기 없고 최대한 미루고 싶어하는 일 중에 하나.

하지만, 전체적인 코드의 유지보수를 위해 주석은 매우 중요.

2.1 한 줄 주석

  - 한 줄 주석은 두개의 슬래시를 이용하여 작성. 그 줄에서 끝남.

  - 보통 두 개의 슬래시를 입력하고 주석을 입력하기 전에 한칸 띄움.

  - 한줄 주석은 3가지 방법으로 사용.

  - 코드를 주석 처리할 떄를 제외하고, 연속적으로 한 줄 주석 사용은 지양.

  - 주석이 길어지면 여러 줄 주석을 사용.

2.2. 여러 줄 주석

  - 여러 줄 주석은 말 그대로 여러 줄에 걸친 주석을 파일에 입력할 떄 사용.

  - /*로 시작하여 */로 끝남.

  - 여러 줄 주석을 이용해 한 줄만 입력해도 되고, 여러 줄로 입력해도 무방.

  - 여러 줄 주석도 한 줄 주석과 마찬가지로 주석 바로 윗 줄은 한 줄을 비우고 설명할 코드 바로 윗줄에 주석 입력.

2.3 주석 쓰기

  - 주석은 개발자 사이에서 항상 많은 논란을 야기.

  - 일반적으로는 명확하기 않은 것에 대해 주석을 쓰고, 코드 자체로 충분히 설명 가능한 부분에는 주석을 사용하지 않는다.

  - 일반적으로 주석은 코드를 명확하게 해야 할 곳에 추가해야 한다.

2.3.1 이해하기 어려운 코드

  - 이해하기 어려운 코드에는 반드시 주석을 추가해야 한다.

  - 코드의 역할에 따라 여러 줄 주석 또는 한 줄 주석을 여러 개 사용하거나 잘 혼용해서 사용.

2.3.2 오해하기 쉬운 코드

  - 다른 개발자로 하여금 오해를 불어일으킬 수 있는 코드에는 주석 작성.

  - 일반적인 로직에서 벗어난 코드라던지, 특별한 이벤트를 위해 어쩔 수 없이 작성된 코드라던지 부가 설명이 없으면 이해할 수 없는 코드에 작성하면 좋다.

2.3.3 특정 브라우저 핵

  - 특정 브라우저를 지원하기 위해 작성한 코드인 경우 주석 작성.

  - 오래된 브라우저의 경우 크로스 브라우징이 안된다거나 브라우저 간 호환이 되지 않아 이를 처리 하기 위해 작성된 코드에는 주석을 작성하도록 한다.

2.4 문서화 주석

  - 문서화 주석은 기술적으로는 자바스크립트에서 지원하는 영역은 아님. 굉장히 많이 사용됨.

  - 문서화 주석에는 다양한 포맷이 있지만 JavaDoc 문서 포맷을 가장 많이 사용.

  - 여러 줄 주석과 유사하지만, 별표가 하나 더 붙어 /** 로 주석을 시작하고 다음줄 부터 항목 마다 @를 앞에 붙힌다.

  - 주석을 문서화하는 툴킷으로 JSDoc도 존재.

  - JSDoc은 특정 라이브러리에 구애받지 않고 사용가능.

  - 오픈소스 프로젝트에서 많이 사용되고 있으며 구글에서도 사용함.

  - 문서화 주석을 사용할 때는 아래 항목을 모두 만족해야 한다.