주석을 달기 어려운 이유
2011/09/09 11:51 by 전규현
All of Software 블로그를 RSS Feed에 등록을 해 놓으시면 편리하게 받아보실 수 있습니다.
RSS Feed
코딩을 하면서 주석을 적절히 잘 달아야 한다는데는 이견이 없을 것이다. 하지만 현실은 주석이 제대로 달린 코드를 찾아보기 어렵다.
"주석이 제대로 달렸다"의 애매한 기준을 명확하게 정리해보면 다음과 같습니다.
그럼 가장 효과적으로 주석을 다는 방법에 대해서 알아보자.
Doxygen이나 Javadoc등의 표준 주석 Notation을 따르면 여러 툴의 많은 도움을 받을 수 있고 가독성이 높아진다. 신입사원이 들어와도 널리 알려진 표준이므로 쉽게 따라할 수 있게 된다.
주석은 코딩하면서 짬짬히 다는 것이 아니다. 코딩 이전에 설계 시 Public function을 정의하면서 주석을 먼저 작성한다. 이렇게 설계를 해서 완벽할 때 구현(코딩)에 들어가면 된다.
코딩을 하면서 Public interface가 자주 바뀌면 주석도 바꾸기 매우 귀찮아지게 된다.
하위 설계는 코드와 주석을 적당히 이용하게 되면 문서로 작성할 필요가 없이 대부분 소스코드로 작성할 수 있다.
모든 소스코드에 주석을 달아야 한다고 하면 헬스클럽 1년 끊어 놓고 일주일 운동하고 포기하는 사태가 발생하게 된다. 당장 바쁜데 언제 시간을 내서 주석을 달 수 있겠는가?
Public function은 다른 개발자들이 가장 빈번하게 참조를 해야 할 함수들이다. 같은 시간에 주석을 달아서 가장 효율성이 높다.
하지만 모든 함수가 Public function이라면 효과도 없고 프로그램은 뒤죽박죽이 된다. 미리 Public function을 정하게 되면 최소화를 할 수 있다. 가능하면 거의 모든 함수를 속으로 숨기고 밖으로 최소한의 Interface만 open할 경우 프로그램도 간결하게 되고 유지보수도 쉬워진다.
Doxygen이나 JavaDoc을 이용하면 API 메뉴얼이 근사하게 나오게 된다. 이 문서만 봐도 개발자들이 개발하는데 대단히 큰 도움을 준다.
이는 소스코드와 주석/설계문서를 지속적으로 일치 시키는데 지대한 도움을 준다.
복잡한 소스코드를 작성하고 주석으로 설명하는 것보다는 약간 효율이 떨어져도 가독성 높게 소스코드를 풀어서 쓰는 것이 좋다. 따라서 함수의 크기는 작게 유지하면서 읽어 내려가기 쉽게 작성하는 것이 좋다.
성능에 목숨거는 알고리즘을 개발하는 것이 아니라면 가독성 높은 소스코드를 작성하는 것을 높은 우선순위로 두는 것이 좋다. 왜냐하면 소스코드는 개발비보다 유지보수비가 몇배 더 들기 때문이다.
Prototyping한 소스코드는 버려야 한다. Prototype은 주석도 없고 에러처리도 안하고 가장 빠르게 검증을 해보는 것이다. 제품화 할 코드는 이것보다 몇배의 시간이 더 걸린다. 따라서 Prototyping을 한 소스코드는 꼭 버리고 제대로 설계를 해서 다시 만들어야 한다. 단, 참조는 가능하다.
강제화를 위해서는 리뷰가 필수이다. 코드 리뷰보다는 설계 리뷰가 중요하다. 설계 단계에서 대부분의 Public interface의 주석을 미리 완성하고 코딩에 들어가면 협업도 원활하고 재작업도 줄어든다. 그리고나서 코딩단계에서의 주석은 크게 강조하지 않아도 될 것이다.
규칙으로 무조건 주석을 달라고 강제하는 것보다는 정공법으로 분석/설계 리뷰를 통해서 설계가 끝났을 때 주석이 이미 달린 소스코드 헤더가 나오는 것이 좋다.
무조건 코딩부터 달려드는 것보다는 한번 더 생각해보고 Public interface를 먼저 정의하고 주석을 작성해서 리뷰하고 코딩을 하는 것이 전체 개발시간을 현저하게 단축 시켜준다. 시간이 없어서 주석도 없는 코딩만 마구 해대는 것은 핑계에 불과하다.
효과적으로 주석을 다는 습관을 가지고 있다면 여러 동료들에게 사랑을 받고 후배들의 존경을 받을 것이다.
* 이 포스트는 blogkorea [블코채널 : 꿈꾸는 소프트웨어 개발자 세상] 에 링크 되어있습니다.
Image by the|G|™
RSS Feed
코딩을 하면서 주석을 적절히 잘 달아야 한다는데는 이견이 없을 것이다. 하지만 현실은 주석이 제대로 달린 코드를 찾아보기 어렵다.
"주석이 제대로 달렸다"의 애매한 기준을 명확하게 정리해보면 다음과 같습니다.
- 과도한 주석은 나쁘다. 비용이 너무 많이 들어간다.
- 소스코드를 활용하고 유지보수하는데 어려움이 없어야 한다.
- 업데이트가 되어서 소스코드와 일치되어야 한다.
- 전체적으로 일관된 표준을 지켜야 한다.
그럼 가장 효과적으로 주석을 다는 방법에 대해서 알아보자.
| 회사의 주석 표준을 정한다. |
Doxygen이나 Javadoc등의 표준 주석 Notation을 따르면 여러 툴의 많은 도움을 받을 수 있고 가독성이 높아진다. 신입사원이 들어와도 널리 알려진 표준이므로 쉽게 따라할 수 있게 된다.
| 주석은 소스코드보다 먼저다. |
주석은 코딩하면서 짬짬히 다는 것이 아니다. 코딩 이전에 설계 시 Public function을 정의하면서 주석을 먼저 작성한다. 이렇게 설계를 해서 완벽할 때 구현(코딩)에 들어가면 된다.
코딩을 하면서 Public interface가 자주 바뀌면 주석도 바꾸기 매우 귀찮아지게 된다.
하위 설계는 코드와 주석을 적당히 이용하게 되면 문서로 작성할 필요가 없이 대부분 소스코드로 작성할 수 있다.
| Public function 위주로 주석을 단다. |
모든 소스코드에 주석을 달아야 한다고 하면 헬스클럽 1년 끊어 놓고 일주일 운동하고 포기하는 사태가 발생하게 된다. 당장 바쁜데 언제 시간을 내서 주석을 달 수 있겠는가?
Public function은 다른 개발자들이 가장 빈번하게 참조를 해야 할 함수들이다. 같은 시간에 주석을 달아서 가장 효율성이 높다.
하지만 모든 함수가 Public function이라면 효과도 없고 프로그램은 뒤죽박죽이 된다. 미리 Public function을 정하게 되면 최소화를 할 수 있다. 가능하면 거의 모든 함수를 속으로 숨기고 밖으로 최소한의 Interface만 open할 경우 프로그램도 간결하게 되고 유지보수도 쉬워진다.
Doxygen이나 JavaDoc을 이용하면 API 메뉴얼이 근사하게 나오게 된다. 이 문서만 봐도 개발자들이 개발하는데 대단히 큰 도움을 준다.
이는 소스코드와 주석/설계문서를 지속적으로 일치 시키는데 지대한 도움을 준다.
| 주석같은 소스코드가 좋다. |
복잡한 소스코드를 작성하고 주석으로 설명하는 것보다는 약간 효율이 떨어져도 가독성 높게 소스코드를 풀어서 쓰는 것이 좋다. 따라서 함수의 크기는 작게 유지하면서 읽어 내려가기 쉽게 작성하는 것이 좋다.
성능에 목숨거는 알고리즘을 개발하는 것이 아니라면 가독성 높은 소스코드를 작성하는 것을 높은 우선순위로 두는 것이 좋다. 왜냐하면 소스코드는 개발비보다 유지보수비가 몇배 더 들기 때문이다.
| Prototyping 시에는 주석이 필요없다. |
Prototyping한 소스코드는 버려야 한다. Prototype은 주석도 없고 에러처리도 안하고 가장 빠르게 검증을 해보는 것이다. 제품화 할 코드는 이것보다 몇배의 시간이 더 걸린다. 따라서 Prototyping을 한 소스코드는 꼭 버리고 제대로 설계를 해서 다시 만들어야 한다. 단, 참조는 가능하다.
| 처음에는 강제화가 필요하다. |
강제화를 위해서는 리뷰가 필수이다. 코드 리뷰보다는 설계 리뷰가 중요하다. 설계 단계에서 대부분의 Public interface의 주석을 미리 완성하고 코딩에 들어가면 협업도 원활하고 재작업도 줄어든다. 그리고나서 코딩단계에서의 주석은 크게 강조하지 않아도 될 것이다.
규칙으로 무조건 주석을 달라고 강제하는 것보다는 정공법으로 분석/설계 리뷰를 통해서 설계가 끝났을 때 주석이 이미 달린 소스코드 헤더가 나오는 것이 좋다.
무조건 코딩부터 달려드는 것보다는 한번 더 생각해보고 Public interface를 먼저 정의하고 주석을 작성해서 리뷰하고 코딩을 하는 것이 전체 개발시간을 현저하게 단축 시켜준다. 시간이 없어서 주석도 없는 코딩만 마구 해대는 것은 핑계에 불과하다.
효과적으로 주석을 다는 습관을 가지고 있다면 여러 동료들에게 사랑을 받고 후배들의 존경을 받을 것이다.
* 이 포스트는 blogkorea [블코채널 : 꿈꾸는 소프트웨어 개발자 세상] 에 링크 되어있습니다.
Image by the|G|™
'프로젝트 > 구현' 카테고리의 다른 글
| 주석을 달기 어려운 이유 (9) | 2011/09/09 |
|---|---|
| Copy & Paste의 종말 (9) | 2009/07/31 |
Trackback Address: http://allofsoftware.net/trackback/235
사랑과 존경을 받는 주석이 맘에 와닿네요. *^^*
제 경우에는 주석 = 종교와 동일한 방식의 자세가
중요 포인트입니다.
대게 모든 함수와 모듈에는 주석을 달아야하고,
로직 코드 내의 주석은 why에 focus를 하는 것이
여러모로 편하더군요.
popopome님 반갑습니다.
후배와 동료의 사랑보다 발뺴기가 편하려고 주석을 달아 놓습니다 ㅋㅋ
구차니님 안녕하세요.
발 못빼게 하려고 주석 안다는 사람도 많습니다.
자기 아니면 다른 사람은 잘 못하게 만들어 놓은 것을 파워라고 생각하는 사람들이죠.
한마디로 물귀신이죠. ^^
주석 이전에 코드에 대한 정리가 먼저 일듯 합니다.
주석이 없는 코드로 주석을 대신할 수 있을정도로 코드에 대한 가독성을 높이는 것이 먼저일듯 하구요.
그 다음이 주석인데... 사실은 주석을 이렇게 저렇게 달아라 하는것은 자치하면 습관성이 될수 있으므로,
코드를 작성하는 것처럼 주석을 작성하는 연습과 교육이 필요할듯 합니다.
저는 개발자가 아니지만 주석은 개발자의 발자취라고 생각되며, 또한 주석 한줄한줄이 소스 못지 않은 자산이라고 생각됩니다.
잘 지내시죠? 뵙고 싶습니다.
황차장님 오랫만입니다.
잘 계시죠? ^^ 조만간에 또 뵐날이 오겠죠.
저는 주석을 소설처럼 다는 스타일입니다 ㅡ.-;
지금 까지 딱3분 빼고 다들 좋아하셨죠.
어쩌면 그만큼 개발자들이 주석달기를 싫어하는 걸 반영하는 걸지도 모르겠습니다.
유지보수해보면 주석 재대로 달린경우를 거의 못본것 같습니다-_-;
이름만 들어도 알만한 회사들 조차 말이죠.
그나마 요즘은 많은 회사들이 퍼블릭펑션에 대한 주석은 강제하는것 같습니다.
(퍼블릭펑션은 시키지 않아도 주석다는 센스는 개발자의 센스라고 생각하지만 말이죠 ㅎㅎㅎ)
안녕하세요. 당근천국님.
Public function을 제대로 구분해서 쓰지 않는 개발자도 수두룩합니다. ^^
public function에 Doxygen으로 주석을 달면 더 좋죠.