•
이 장에서는 문서화에 대한 전체적인 내용을 살펴보고 주석이라는 문서화 형태의 일종을 알아본다.
코드를 작성할 때, 당신의 코드를 유지보수하는 사람이 당신이 어디사는지 알고있는 싸이코패스라고 생각하면서 작성해라. - 익명
1. 외부 문서
•
외부 문서는 문제 정의와 요구사항, 아키텍처의 문서와 비교했을 때 상대적으로 추상화 수준이 높은 경향이 있다.
•
단위 개발 일지
◦
단위 개발 일지 또는 소프트웨어 개발 일지라고도 하며 이는 개발자가 구현 중에 사용했던 기록이 담겨 있는 비공식적인 문서다.
▪
단위는 일반적으로 하나의 클래스를 의미하며 패키지나 컴포넌트를 의미할 수도 있다.
•
상세 설계 문서
◦
상세 설계 문서는 하위 추상화 수준을 가지는 설계 문서다.
◦
이 문서는 클래스 수준 또는 메소드 수준의 설계 시 결정 사항과 고려했던 대안, 그리고 최종 접근 방법을 선택한 이유를 기술한다.
◦
때때로 공식 문서에 포함되기도 하며 일반적으로 상세 설계를 구현과 분리하여 생각한다.
2. 문서화를 위한 프로그래밍 스타일
•
내부 문서는 프로그램 코드 안에 존재한다. 이는 소스 명령문 수준의 가장 상세한 문서다.
•
코드 수준의 문서에 가장 크게 기여하는 것은 주석이 아니라 좋은 프로그래밍 스타일이다.
◦
스타일에는 좋은 프로그램 구조, 직관적이고 이해하기 쉬운 접근 방법의 사용, 좋은 변수 이름, 좋은 메소드 이름, 상수 사용, 명확한 배치, 제어 흐름과 데이터 구조 복잡성의 최소화가 포함된다.
•
즉 프로그래밍 스타일을 향상시키는 것만으로도 문서로 전달해야할 많은 내용들을 생략할 수 있는 의미를 전달할 수 있다.
3. 주석을 작성할 것인가? 작성하지 않을 것인가?
•
주석은 코드의 추상화 수준보다는 조금 더 높은 수준에서 개발자가 구현하고자 하는 의미를 설명해야 한다.
◦
코드가 하는 일을 그대로 나열하는 형태의 주석은 좋은 형태의 주석이 아니다.
•
주석을 작성하면서 내가 작성한 코드가 무슨 일을 하는지 좀 더 진지하게 생각해볼 수 있다.
4. 효과적인 주석을 위한 핵심 사항
주석의 종류
•
주석은 보통 여섯 가지 종류로 분류할 수 있다.
◦
코드 반복
▪
코드가 하는 일을 말만 바꾸어 다시 말하는 주석이다. 추가적인 정보를 제공하지는 않고 읽어야 하는 코드의 양만 늘린다.
◦
코드 설명
▪
일반적으로 복잡하거나 미묘한 코드를 설명하는 데 사용되는 주석이다. 코드가 복잡하다면 유용하지만 일반적으로는 코드가 혼란스럽게 작성되었기 때문이다.
▪
코드가 설명이 필요할 정도로 복잡하다면 주석을 다는 것보다는 코드를 향상시키는 것이 대부분의 경우 더 낫다.
▪
코드 자체를 명확하게 만들고 나서 개요나 의도를 나타내는 주석을 사용하도록 한다.
◦
코드 표시 기능
▪
to do 태그를 이용하여 뭔가를 표시할 수 있다.
◦
코드 요약
▪
코드를 요약하는 주석은 그저 요약만 한다. 이러한 주석은 코드를 더 빠르게 살펴볼 수 있어 코드 반복보다는 훨씬 가치있다.
▪
요약 주석은 코드를 작성한 사람보다는 다른 사람이 코드를 유지보수할 때 특히 유용하다.
◦
코드의 의도를 설명
▪
의도 수준의 주석은 코드의 목적을 설명한다. 이는 해결책 수준보다는 문제 수준에서 사용된다.
•
현재 직원 정보를 가져온다. → 코드의 의도를 설명
•
employeeRecord 객체를 갱신한다. → 해결책에 대한 요약 주석
▪
코드 자체로는 표현할 수 없는 정보
•
저작권 설명, 기밀 사항, 버전 번호 등의 세부사 항들은 코드 자체로 표현할 수 없다.
◦
완성된 코드에 허용되는 주석의 종류는 코드로 표현할 수 없는 정보와 의도 주석, 요약 주석이다.
효율적인 주석 작성
•
주석을 작성하는 스타일이 오래 걸리거나 장황한 경우가 있다. 그렇다면 새로운 스타일을 찾아라.
◦
많은 작업이 필요한 주석 작성 스타일은 유지보수할 때 골치 아프다.
•
프로그램이 무엇을 하는지 설명하기 위한 단어가 쉽게 떠오르지 않아서 주석을 작성하기 어렵다.
◦
이것은 대개 개발자가 프로그램이 하는 일을 제대로 이해하지 못한다는 신호다.
•
다음은 주석을 효율적으로 작성하기 위한 가이드라인이다.
◦
변경하기 어렵지 않은 스타일을 이용하라.
◦
주석 작성 시간을 줄이기 위하여 의사코드 프로그래밍 프로세스를 사용하라.
◦
주석을 개발 스타일에 포함시켜라.
가장 적당한 주석 수
•
캐퍼스 존스는 IBM의 연구에서 명령문 10개마다 주석을 하나 작성했을 때 이해도가 가장 높아진다는 사실을 발견했다.
•
각 주석이 효율적인지 초점을 맞추고 불필요한 주석은 없애라.
5. 주석 스타일(다시 봐보기)
•
주석을 적용하고자 하는 수준인 프로그램, 파일, 메소드, 단락, 개별 줄에 따라 여러 다른 기법들을 활용하여 작성할 수 있다.
개별 줄에 주석 작성
•
코드의 줄마다 주석을 작성해야하는 경우는 다음과 같다.
◦
해당 줄의 코드가 설명이 필요없을 정도로 복잡하다.
◦
해당 줄에서 오류가 발생한 적이 있어 이를 기록하고 싶다.
•
다음은 이에 대한 가이드라인이다.
◦
제 멋대로인 주석은 피하라.
◦
한 줄짜리 줄 끝 주석을 피하라.
◦
코드 여러 줄에 대한 줄 끝 주석을 피하라.
▪
하나의 줄 끝 주석을 한 줄 이상의 코드에 적용하고자 하면 주석이 어떤 줄에 해당하는 내용인지 확인할 수 없다.
•
줄 끝 주석을 사용해야 할 때
◦
데이터 선언에 주석을 작성하기 위해서 줄 끝 주석을 사용할 수 있다.
◦
유지보수 기록을 위해서 줄 끝 주석을 사용하지 말라.
◦
블록의 끝을 표시하기 위해서 줄 끝 주석을 사용하라.
•
특별한 두 가지 경우를 제외하면 줄 끝 주석은 개념적인 문제를 가지고 있고 코드를 복잡하게 만들기 쉽다. 결론적으로 피하는 것이 상책이다.
단락에 주석 작성
•
문서화가 잘된 프로그램의 주석 대부분은 한두 문장으로 코드 단락을 설명한다.
•
다음은 단락을 잘 사용하기 위한 가이드라인이다.
◦
코드의 의도를 나타내기 위한 주석을 작성하라.
▪
주석 다음에 오는 코드 블록의 목적을 설명하라.
◦
문서화에 들일 노력을 코드 작성에 들여라.
◦
단락 주석을 작성할 때 방법보다는 그 이유를 집중적으로 다루어라.
◦
코드를 읽는 개발자에게 다음에 오는 내용을 알려주기 위하여 주석을 작성하라.
◦
주석을 소중하게 여겨라.
◦
일반적이지 않은 내용을 문서화하라.
◦
축약하지 마라.
◦
중심 주석과 부차적인 주석을 구별하라.
◦
프로그래밍 언어나 개발 환경에서의 오류나 문서화되어 있지 않은 기능에 관한 내용을 주석으로 작성하라.
데이터 선언에 주석 작성
•
수치 데이터의 단위를 주석으로 작성하라.
•
허용 가능한 값의 범위를 주석으로 작성하라.
•
변수의 의미를 주석으로 작성하라.
•
입력 데이터의 한계를 주석으로 작성하라.
•
변수와 연관된 주석에 변수의 이름을 입력하라.
•
전역 데이터를 문서화하라.
제어 구조에 주석 작성
•
제어 구조 앞에 있는 공간이 일반적으로 주석을 입력하기 좋은 위치다.
•
다음은 이에 대한 몇 가지 가이드라인이다.
◦
if나 case, 반복문, 명령문 블록 앞에 주석을 입력하라.
◦
각 제어 구조의 끝에 주석을 작성하라.
메소드에 주석 작성
•
다음은 메소드 주석을 위한 몇 가지 가이드라인이다.
◦
설명하는 코드와 가까운 곳에 주석을 작성하라.
◦
메소드의 위에 한두 문장으로 각 메소드를 설명하라.
◦
매개변수를 선언한 곳에서 문서화하라.
◦
Javadoc과 같은 코드 문서화 유틸리티를 활용하라.
◦
입력과 출력 데이터를 구별하라.
◦
인터페이스 가정을 문서화하라.
◦
사용되는 전역 변수를 문서화하라.
◦
메소드의 한계에 대해서 주석을 작성하라.
◦
메소드의 사이드 이펙트를 문서화하라.
◦
사용된 알고리즘의 출처를 작성하라.
◦
프로그램의 위치를 표시하기 위하여 주석을 사용하라.
클래스와 파일, 프로그램에 대한 주석 작성
•
클래스와 파일, 프로그램은 여러 모듈을 포함하고 있다는 특징이 있다.
•
이러한 경우의 문서 작업은 파일이나 클래스, 프로그램의 내용에 대해 의미 있고 상위 수준의 관점을 제공해야 한다.
•
클래스 문서를 작성하기 위한 일반적인 가이드라인
◦
클래스에 대한 설계 접근 방법을 기술하라.
◦
한계와 사용 가정 등을 기술하라.
◦
인터페이스를 기술하라.
•
파일 문서화를 위한 일반적인 가이드라인
◦
각 파일의 목적과 내용을 설명하라.
◦
버전 관리 태그를 넣어라.
◦
주석 블록에 법적인 사항을 넣어라.
◦
파일 이름은 내용과 관련된 이름으로 지어라.
6. IEEE 표준
•
소스코드 수준을 벗어난 문서화에 대해서는 IEEE가 훌륭한 정보를 제공한다.
•
다음은 소프트웨어 프로젝트에 가장 적합한 몇 가지 국내외 표준이다.
◦
최상위 표준은 ISO/IEC 표준 12207, Information Technology. Software Life Cycle Processes다.
요점 정리
•
주석을 작성할 것이냐는 질문은 합당하다. 주석은 잘못 작성하면 시간 낭비일 뿐만 아니라 때로는 해롭기도 하다.
•
소스코드는 프로그램에 대해 대부분의 중요한 정보를 포함해야 한다. 프로그램이 실행되는 한 소스코드가 다른 어떤 리소스보다 최신으로 유지될 가능성이 높으므로 중요한 정보를 코드에 담는 것이 유용하다.
•
좋은 코드는 그 자체로 훌륭한 문서다 코드가 추가적인 주석이 필요할 정도로 나빠지면 우선 추가적인 주석이 필요 없게 코드를 향상시키려고 해야 한다.
•
주석은 그 자체로는 설명되지 않는 코드에 대한 요약 수준이나 문제 수준에서 다뤄야 한다.
•
어떤 주석 스타일은 손이 많이 간다. 관리하기 쉬운 스타일을 사용하라.
