32장: 스스로를 설명하는 코드

32장: 스스로를 설명하는 코드

  • 소프트웨어 문서에는 소스 코드 밖의 외부 문서와 소스 코드 안의 내부 문서가 있음.
  • 내부 문서의 중심은 주석이 아니라 좋은 프로그래밍 스타일임. 명확한 구조와 이름으로 코드가 대부분을 설명하게 한 뒤, 코드만으로 표현할 수 없는 정보만 주석으로 보충함.
  • 주석은 많다고 좋은 것이 아님. 코드의 반복, 오래된 설명, 유지하기 어려운 장식은 이해를 돕기는커녕 방해함.

32.1 외부 문서

  • 외부 문서는 별도 문서나 단위 개발 폴더에 기록되는 정보임.
  • 대규모의 형식적인 프로젝트에서는 문서 대부분이 소스 코드 밖에 있음.

  • 구축 단계의 외부 문서는 문제 정의·요구사항·아키텍처 문서보다는 상세하고, 실제 코드보다는 높은 수준을 다룸.

  • 단위 개발 폴더
    • 단위 개발 폴더(Unit Development Folder, UDF) 또는 소프트웨어 개발 폴더(Software Development Folder, SDF)는 구축 중 개발자가 사용하는 비형식 문서임.
    • 여기서 단위는 보통 클래스지만 패키지나 컴포넌트일 수도 있음.
    • 다른 문서에 남지 않은 설계 결정의 흔적을 보존하는 것이 주된 목적임.
    • 관련 요구사항 사본, 단위가 구현하는 상위 설계 부분, 개발 표준, 현재 코드 목록, 설계 메모 등을 담을 수 있음.
    • 고객에게 납품하는 프로젝트도 있고 내부 자료로만 쓰는 프로젝트도 있음.
  • 상세 설계 문서
    • 클래스 또는 루틴 수준의 설계 결정, 검토한 대안, 특정 접근법을 선택한 이유를 기록함.
    • 정식 문서로 작성하면 상세 설계 활동을 구축과 분리해 다루기도 함.
    • 개발자의 메모를 UDF에 모으는 형태일 수도 있고, 별도 문서 없이 코드 자체에만 남을 수도 있음.

32.2 문서로서의 프로그래밍 스타일

  • 내부 문서는 프로그램 목록 안에 있으며 소스 문장 수준의 가장 상세한 문서임.
  • 코드와 가장 가까이 있으므로 코드가 바뀔 때 함께 최신 상태로 유지될 가능성이 큼.
  • 코드 수준 문서화의 가장 큰 기여자는 주석이 아니라 좋은 프로그래밍 스타일임.
  • 좋은 스타일에는 다음 요소가 포함됨.
    • 좋은 프로그램 구조
    • 단순하고 이해하기 쉬운 접근법
    • 의미가 분명한 변수 이름과 루틴 이름
    • 리터럴 대신 이름 있는 상수 사용
    • 논리 구조가 보이는 레이아웃
    • 제어 흐름과 데이터 구조의 복잡성 최소화
  • 의미 없는 이름과 거친 레이아웃을 사용하면 주석이 없어 무엇을 하는 코드인지 파악하기 어려움.
  • 같은 코드라도 i, j, meetsCriteria 대신 primeCandidate, factor, factorableNumber, isPrime처럼 역할이 드러나는 이름을 쓰면 소수 탐색이라는 목적이 보임.
  • 명확성을 위해 중간 변수를 추가하는 것도 문서화의 일부임. 실행에 꼭 필요하지 않더라도 계산의 의미를 드러낼 수 있음.
  • 스스로를 설명하는 코드는 좋은 스타일이 문서화 부담의 대부분을 맡고, 주석은 가독성을 마무리하는 역할만 함.

체크리스트: 스스로를 설명하는 코드

클래스

  • 클래스 인터페이스가 일관된 추상화를 제공하는가?
  • 클래스 이름이 중심 목적을 설명하는가?
  • 인터페이스만 보고 클래스 사용법을 알 수 있는가?
  • 구현 방법을 생각하지 않고 클래스를 블랙박스로 다룰 수 있을 만큼 인터페이스가 추상적인가?

루틴

  • 각 루틴 이름이 실제로 하는 일을 정확히 설명하는가?
  • 각 루틴이 잘 정의된 작업 하나만 수행하는가?
  • 독립 루틴으로 분리하면 좋은 부분을 실제로 분리했는가?
  • 각 루틴의 인터페이스가 명확한가?

데이터 이름

  • 형식 이름이 데이터 선언의 의미를 설명할 만큼 구체적인가?
  • 변수 이름이 역할을 정확히 나타내는가?
  • 변수가 그 이름으로 표현한 목적에만 사용되는가?
  • 반복문 계수기에 i, j, k보다 의미 있는 이름을 사용했는가?
  • 임시 플래그나 불리언 변수 대신 이름이 분명한 열거형을 사용했는가?
  • 매직 넘버와 매직 문자열 대신 이름 있는 상수를 사용했는가?
  • 명명 규칙으로 형식, 열거형, 상수, 지역 변수, 클래스 변수, 전역 변수를 구분하는가?

데이터 구성

  • 필요할 때 명확성을 위한 변수를 추가했는가?
  • 같은 변수에 대한 참조가 서로 가까이 있는가?
  • 복잡성을 줄이는 단순한 데이터 형식을 사용하는가?
  • 복잡한 데이터에는 추상 접근 루틴 또는 추상 데이터형을 통해 접근하는가?

제어

  • 코드를 따라가는 정상 경로가 분명한가?
  • 관련 문장을 한데 묶었는가?
  • 비교적 독립적인 문장 묶음을 별도 루틴으로 만들었는가?
  • 정상적인 경우가 else가 아니라 if 뒤에 오는가?
  • 제어 구조를 단순하게 유지했는가?
  • 각 반복문이 잘 정의된 기능 하나만 수행하는가?
  • 중첩을 최소화했는가?
  • 추가 불리언 변수, 불리언 함수, 결정표를 사용해 복잡한 불리언 식을 단순화했는가?

레이아웃

  • 프로그램 레이아웃이 논리 구조를 보여 주는가?

설계

  • 코드가 직관적이며 불필요한 기교를 피하는가?
  • 구현 세부를 가능한 한 숨겼는가?
  • 컴퓨터 과학이나 프로그래밍 언어의 구조보다 문제 영역의 용어로 프로그램을 작성했는가?

32.3 주석을 쓸 것인가, 쓰지 않을 것인가

주석 대화

  • 주석은 잘 쓰기보다 잘못 쓰기 쉬우며, 잘못된 주석은 도움보다 해가 될 수 있음.
  • 주석을 반대하는 근거도 타당한 부분이 있음.
    • 자연어는 코드보다 장황하고 모호할 수 있음.
    • 코드 변경을 따라가지 못한 주석은 독자를 잘못된 방향으로 이끔.
    • 코드를 그대로 반복하는 주석은 읽을 분량만 늘림.
  • 주석을 지지하는 근거 역시 타당함.
    • 좋은 주석은 코드가 아니라 코드의 의도를 더 높은 추상화 수준에서 설명함.
    • 주석을 훑어보며 수정할 위치를 빠르게 찾을 수 있음.
    • 요구사항과 구현을 연결하고, 코드에 직접 표현되지 않은 사실을 전달할 수 있음.
  • 몇 줄마다 주석 하나 같은 양적 기준은 적절하지 않음. 필요한 곳에 유용한 주석을 쓰는 것이 목적임.
  • 코드가 불명확하면 먼저 코드를 고쳐야 함. 좋은 이름, 루틴 추출, 단순한 제어 흐름으로 개선한 뒤에도 남는 의도와 배경을 주석으로 기록함.
  • 주석을 쓰느냐의 문제가 아니라 어떤 주석이 실제로 가치가 있느냐가 핵심임.

32.4 효과적인 주석의 핵심

  • 잘못된 주석은 없는 주석보다 나쁨.

주석의 종류

  • 주석은 여섯 종류로 구분할 수 있음.

  • 코드의 반복
    • 피해야 함.
  • 코드의 설명
    • 먼저 코드를 명확하게 고친 다음 요약 또는 의도 주석을 사용함.
  • 코드 안의 표식
    • 완료되지 않은 작업을 개발자에게 알리는 임시 메모임.
    • TODO, FIXME처럼 하나의 표준 형식을 정해야 출시 전에 기계적으로 검색할 수 있음.
    • 여러 표식을 제각각 사용하면 미완성 코드를 검색에서 놓칠 수 있음.
    • 컴파일을 일부러 실패시키는 표식이나 편집기의 할 일 태그도 활용할 수 있으나, 릴리스 체크리스트에서 반드시 제거 여부를 확인해야 함.
  • 코드의 요약
    • 코드 전체를 읽지 않고도 빠르게 훑을 수 있어 유지보수에 유용함.
  • 코드 의도의 설명
    • 해결 방법이 아니라 해당 코드 부분의 목적을 문제 영역 수준에서 설명함.
    • employeeRecord 객체 갱신은 해결책 수준의 요약이고, 현재 직원 정보 조회는 문제 수준의 의도에 가까움.
    • 요약과 의도의 경계가 항상 명확한 것은 아니며 실무에서는 구분 자체보다 유용한 정보를 주는지가 중요함.
  • 코드 자체로는 표현할 수 없는 정보
    • 저작권·기밀 고지, 버전 번호, 설계 메모, 관련 요구사항·아키텍처 문서 참조, 온라인 자료 링크, 최적화 근거, Javadoc·Doxygen용 정보 등이 해당함.
    • 완성된 코드에 적절한 주석은 이 정보와 의도 주석, 요약 주석임.

효율적인 주석 작성

  • 수정할 때 무너지거나 수정을 방해하지 않는 스타일을 사용하라
    • 점선 정렬, 양쪽 별표 테두리, 글자 수에 맞춘 밑줄처럼 손으로 계속 맞춰야 하는 장식은 피함.
    • 유지 비용이 크면 주석을 고치지 않게 되고 결국 코드와 불일치함.
    • 보기 좋은 주석보다 정확하고 쉽게 수정되는 주석이 중요함.
// 유지하기 어려움: 값이 길어질 때 점을 다시 정렬해야 함
// timeoutMs ........ 요청 제한 시간

// 유지하기 쉬움
// 요청 제한 시간(밀리초)
int timeoutMs;
  • 의사코드 프로그래밍 과정을 사용해 주석 작성 시간을 줄여라
  • 주석 작성을 개발 스타일에 통합하라
  • 성능은 주석을 피할 좋은 이유가 아니다

최적의 주석 수

  • IBM 연구에서는 문장 약 10개당 주석 하나일 때 명확성이 가장 높았지만, 이 수치를 기계적인 규칙으로 사용하면 안 됨.
  • 주석이 너무 적으면 코드를 이해하기 어렵고 너무 많아도 이해를 방해함.
  • 5줄마다 주석 하나 같은 표준은 불명확한 코드를 작성하는 원인을 해결하지 못함.
  • 의사코드 프로그래밍 과정을 제대로 적용하면 몇 줄마다 주석이 자연스럽게 생길 수 있지만, 이는 과정의 결과일 뿐 목표가 아님.
  • 주석 개수가 아니라 각 주석이 코드가 작성된 이유를 설명하고 읽는 비용만큼의 정보를 제공하는지 판단함.

32.5 주석 작성 기법

  • 주석 기법은 적용 범위에 따라 프로그램, 파일, 루틴, 코드 문단, 개별 줄 수준으로 나뉨.

개별 줄에 주석 달기

  • 좋은 코드에서 개별 줄을 설명해야 하는 경우는 드묾.
  • 한 줄이 설명이 필요할 정도로 복잡하거나, 과거 결함과 관련된 중요한 사실을 기록해야 할 때만 고려함.
  • 자기만족적인 주석을 피하라

줄 끝 주석과 문제점

  • 줄 끝 주석은 코드 오른쪽에 배치하므로 시각적 구조를 방해하지 않게 정렬해야 함.
  • 코드 길이가 바뀔 때마다 위치를 다시 맞춰야 해서 유지하기 어려움.
  • 사용할 수 있는 폭이 좁아 설명을 명확하게 쓰기보다 짧게 줄이는 데 신경 쓰게 됨.
  • 한 줄에 대한 줄 끝 주석을 피하라
  • 여러 코드 줄에 대한 줄 끝 주석을 피하라
memorySize = AvailableMemory(); // 사용 가능한 메모리 크기를 구함
  • 위 주석은 코드에서 이미 드러나는 동작을 되풀이하므로 제거하는 편이 나음.

줄 끝 주석을 사용할 때

  • 데이터 선언에 주석을 달 때 줄 끝 주석을 사용하라
    • 충분한 가로 폭이 있다면 선언 옆에서 단위, 범위, 의미를 설명하는 데 유용함.
int sortedBoundary = 0; // 배열에서 정렬이 끝난 마지막 위치
  • 유지보수 기록에 줄 끝 주석을 사용하지 마라
    • 수정 날짜, 작성자 이니셜, 결함 번호는 버전 관리 시스템에 기록함.
    • 주석은 과거에 왜 실패했는지가 아니라 현재 코드가 왜 올바르게 동작하는지를 설명해야 함.
  • 블록의 끝을 표시할 때 줄 끝 주석을 사용하라
    • 길거나 중첩된 반복문과 조건문의 끝을 표시하는 예외적인 용도는 유용함.

코드 문단에 주석 달기

  • 잘 문서화된 프로그램의 주석 대부분은 코드 문단 하나를 설명하는 한두 문장임.
  • 코드의 의도 수준에서 주석을 작성하라
    • 모든 문자를 검사해 $를 찾음보다 $로 표시된 명령어 종결자를 찾음이 더 많은 정보를 줌.
  • 문서화 노력의 초점을 코드 자체에 맞춰라
  • 문단 주석은 방법보다 이유에 초점을 맞춰라
    • 새 계정을 만드는 경우는 조건이 필요한 이유를 알려 줌.
  • 앞에 나올 내용을 독자가 준비할 수 있게 주석을 사용하라
  • 모든 주석이 제값을 하게 하라
  • 뜻밖의 사실을 문서화하라
// 이 컴파일러에서는 2로 나누기보다 오른쪽 시프트가 반복 시간을 75% 줄임
value = value >> 1;
  • 약어를 피하라
    • 가장 널리 알려진 약어가 아니면 풀어 씀. 주석을 해독하는 추가 작업이 필요해서는 안 됨.
  • 주요 주석과 부차적인 주석을 구분하라
    • 밑줄이나 모두 대문자로 구분하면 장식이 과도해지고 일관성을 유지하기 어려움.
    • 부차적 주석 앞에 말줄임표를 붙이거나, 더 좋은 방법으로 부차적 작업을 별도 루틴으로 추출함.
    • 한 루틴 안에 서로 다른 논리 수준이 섞여 있다면 주석 형식보다 루틴 구조를 먼저 개선함.
  • 언어나 환경의 오류 또는 문서화되지 않은 기능을 우회하는 코드는 모두 주석으로 설명하라
    • 어떤 조건에서 문제가 발생하는지, 왜 특수 처리가 필요한지, 관련 결함이나 문서의 위치를 기록함.
    • 우회에 사용하는 숫자도 이름 있는 상수로 바꿈.
  • 좋은 프로그래밍 스타일을 위반한 이유를 정당화하라
    • 의도적으로 규칙을 어긴 경우 이유를 적어, 유지보수자가 정상적인 스타일로 고치다가 동작을 깨뜨리지 않게 함.
  • 까다로운 코드에 주석을 달지 말고 다시 작성하라
    • 주석은 이해하기 어려운 코드를 구해 주지 못함.
    • 처음 작성하는 코드라면 단순하게 다시 쓰고, 재작성 권한이 없는 유지보수 상황에서만 까다로운 부분을 주석으로 보완함.

데이터 선언에 주석 달기

  • 변수 이름만으로 표현할 수 없는 데이터의 속성을 설명함.
  • 수치 데이터의 단위를 주석으로 설명하라
    • 길이, 시간, 좌표 등의 단위를 명시함.
    • 가능하다면 altitudeInMeters처럼 단위를 변수 이름에 넣는 편이 더 강한 문서화임.
  • 허용되는 수치 범위를 주석으로 설명하라
    • 언어의 형식 체계로 범위를 제한할 수 없다면 예상 최솟값과 최댓값을 기록함.
    • 실행 중 검증이 필요하면 주석만 쓰지 말고 단언문도 사용함.
  • 코드화된 의미를 주석으로 설명하라
    • 열거형을 지원하면 숫자 코드 대신 열거형을 우선 사용함.
  • 입력 데이터의 한계를 주석으로 설명하라
    • 매개변수, 파일, 사용자 입력에 허용되는 값과 허용되지 않는 값을 기록함. <- assert로하는것이 더 바람직해보임
  • 플래그를 비트 수준까지 문서화하라
  • 변수 관련 주석에 변수 이름을 표시하라
  • 전역 데이터를 문서화하라

제어 구조에 주석 달기

  • 제어 구조 앞은 주석을 배치하기 자연스러운 위치임.
  • 조건문과 case에는 판단 이유와 결과를, 반복문에는 반복의 목적을 설명함.
  • 각 if, case, 반복문 또는 문장 블록 앞에 주석을 두어라
  • 각 제어 구조의 끝에 주석을 달아라
  • 반복문 끝 주석을 코드가 복잡하다는 경고로 받아들여라
while (*input != ',' && *input != END_OF_STRING) {
    *field++ = *input++;
} // while — 쉼표 앞의 입력 필드 복사

루틴에 주석 달기

  • 주석을 설명 대상 코드 가까이에 두어라
  • 각 루틴의 맨 위에서 한두 문장으로 루틴을 설명하라
    • 짧게 설명하기 어렵다면 루틴의 목적이 불분명하거나 책임이 너무 많다는 신호임.
  • 매개변수가 선언된 곳에서 매개변수를 문서화하라
  • Javadoc 같은 코드 문서화 도구를 활용하라
  • 입력 데이터와 출력 데이터를 구분하라
    • 언어가 입출력 방향을 문법으로 표현하지 못하면 in, out, in/out을 명시함.
  • 인터페이스 가정을 문서화하라
    • 합법·불법 값, 정렬된 배열, 초기화 상태, 유효한 멤버 데이터 등의 전제 조건을 기록함.
    • 가정을 발견한 즉시 적고, 가능하면 단언문으로 검증함.
  • 루틴의 한계를 주석으로 설명하라
    • 결과 정확도, 정의되지 않는 조건, 오류 시 기본 동작, 지원하는 배열·테이블 크기, 알려진 함정을 기록함.
  • 루틴의 전역 효과를 문서화하라
  • 사용한 알고리즘의 출처를 문서화하라
  • 주석으로 프로그램의 부분을 표시하라
    • 일관된 표식이나 @param, @version, @throws 같은 태그를 사용하면 편집기 탐색과 문서 추출을 자동화할 수 있음.

클래스, 파일, 프로그램에 주석 달기

  • 클래스, 파일, 프로그램은 여러 루틴을 포함함.
  • 이 수준의 문서는 포함된 내용을 이해할 수 있는 의미 있는 상위 수준 관점을 제공해야 함.

클래스 문서화의 일반 지침

  • 클래스의 설계 접근법을 설명하라
    • 코드 세부만 보고 역으로 알아내기 어려운 설계 철학, 전체 접근법, 검토했다가 버린 대안을 기록함.
  • 한계, 사용 가정 등을 설명하라
    • 입출력 가정, 오류 처리 책임, 전역 효과, 알고리즘 출처를 포함해 설계가 부과하는 제약을 기록함.
  • 클래스 인터페이스에 주석을 달아라
  • 클래스 인터페이스에 구현 세부를 문서화하지 마라

파일 문서화의 일반 지침

  • 각 파일의 목적과 내용을 설명하라
    • 파일에 포함된 클래스와 루틴을 설명함.
    • 한 파일에 여러 클래스를 넣었다면 함께 있어야 하는 이유를 밝힘.
    • 원하는 기능이 이 파일에 있는지 머리말만 보고 판단할 수 있어야 함.
  • 블록 주석에 이름, 이메일 주소, 전화번호를 넣어라
  • 버전 관리 태그를 포함하라
    • 버전 관리 도구가 파일 안에 자동 확장하는 태그를 지원한다면 이를 사용해 수작업 없이 최신 버전 정보를 유지함.
  • 블록 주석에 법적 고지를 포함하라
  • 내용과 관련된 파일 이름을 사용하라
    • Java처럼 언어 자체가 클래스와 파일 이름의 일치를 요구하는 경우도 있음.

프로그램 문서화를 위한 책 패러다임

  • 프로그램을 책처럼 구성해 위에서 아래로 읽기, 아래에서 위로 추적하기, 특정 항목 찾기를 모두 지원함.
  • 긴 동질적 코드 목록 대신 기억하기 쉬운 덩어리로 나누고 상위 수준과 하위 수준의 조직 단서를 함께 제공함.
  • 서문은 파일 시작의 소개 주석처럼 프로그램 전체의 개요를 제공함.
  • 목차는 최상위 파일, 클래스, 루틴을 목록이나 구조도로 보여 줌.
  • 절은 루틴 안의 선언부, 데이터 선언, 실행문 같은 구분을 나타냄.
  • 상호 참조는 줄 번호를 포함한 코드 참조 지도를 제공함.
  • 책의 조판 원리를 적용한 실험에서는 전통적인 코드 목록보다 유지보수 시간이 약 25% 줄고 점수가 평균 약 20% 높았음.
  • 상위 구조와 하위 구조를 함께 설명하는 문서가 코드 이해를 돕는다는 점이 핵심임.

32.6 IEEE 표준

  • 소스 코드 수준을 넘어선 문서를 만들 때 IEEE 소프트웨어 공학 표준을 참고할 수 있음.
  • 각 표준은 해당 영역의 개요와 필요한 문서의 윤곽을 제공함.
  • IEEE 외에도 ISO, EIA, IEC가 표준 작업에 참여하며 일부 표준은 공동으로 채택됨.
  • 표준 이름은 표준 번호, 채택 연도, 표준명으로 구성됨.
  • 최상위 표준인 ISO/IEC Std 12207은 소프트웨어 프로젝트의 개발과 관리를 위한 생명주기 프레임워크를 정의함. 미국에서는 IEEE/EIA Std 12207로 채택됨.

소프트웨어 개발 표준

  • IEEE Std 830-1998: 소프트웨어 요구사항 명세 권장 실무
  • IEEE Std 1233-1998: 시스템 요구사항 명세 개발 지침
  • IEEE Std 1016-1998: 소프트웨어 설계 설명 권장 실무
  • IEEE Std 828-1998: 소프트웨어 형상 관리 계획 표준
  • IEEE Std 1063-2001: 소프트웨어 사용자 문서 표준
  • IEEE Std 1219-1998: 소프트웨어 유지보수 표준

소프트웨어 품질 보증 표준

  • IEEE Std 730-2002: 소프트웨어 품질 보증 계획 표준
  • IEEE Std 1028-1997: 소프트웨어 검토 표준
  • IEEE Std 1008-1987(R1993): 소프트웨어 단위 테스트 표준
  • IEEE Std 829-1998: 소프트웨어 테스트 문서 표준
  • IEEE Std 1061-1998: 소프트웨어 품질 메트릭 방법론 표준

관리 표준

  • IEEE Std 1058-1998: 소프트웨어 프로젝트 관리 계획 표준
  • IEEE Std 1074-1997: 소프트웨어 생명주기 프로세스 개발 표준
  • IEEE Std 1045-1992: 소프트웨어 생산성 메트릭 표준
  • IEEE Std 1062-1998: 소프트웨어 획득 권장 실무
  • IEEE Std 1540-2001: 소프트웨어 생명주기 프로세스의 위험 관리 표준
  • IEEE Std 1490-1998: PMI 프로젝트 관리 지식 체계 채택 지침

표준 개요

  • IEEE Software Engineering Standards Collection, 2003 Edition은 당시 최신 ANSI/IEEE 소프트웨어 개발 표준 40개를 모은 자료임.
  • 각 표준의 문서 윤곽, 구성 요소 설명, 포함 이유를 제공함.
  • 품질 보증, 형상 관리, 테스트, 요구사항, 검증과 확인, 설계, 프로젝트 관리, 사용자 문서 표준을 폭넓게 포함함.
  • James W. Moore의 Software Engineering Standards: A User’s Road Map은 IEEE 소프트웨어 공학 표준의 전체적인 길잡이를 제공함.

추가 자료

  • Diomidis Spinellis, Code Reading: The Open Source Perspective: 대규모 코드 기반을 읽는 방법, 읽을 코드의 탐색, 지원 도구 등 실용적인 코드 읽기 기법을 다룸.
  • SourceForge.net: 여러 언어로 작성된 실제 규모의 공개 소스 코드를 통해 좋은 사례와 나쁜 사례를 모두 관찰할 수 있음.
  • Sun Microsystems, How to Write Doc Comments for the Javadoc Tool: @tag 형식, 주석 문장 작성법 등 Java 코드 수준 문서화 규칙을 설명함.
  • Steve McConnell, Software Project Survival Guide: 중간 규모의 업무 핵심 프로젝트에 필요한 문서와 관련 템플릿을 다룸.
  • Construx.com: 문서 템플릿, 코딩 규칙, 소프트웨어 문서화 자료를 제공함.
  • Ed Post, Real Programmers Don’t Use Pascal: 가독성을 대수롭지 않게 여기던 과거 프로그래밍 문화를 풍자함.

체크리스트: 좋은 주석 작성 기법

일반

  • 처음 코드를 접한 사람이 곧바로 이해하기 시작할 수 있는가?
  • 주석이 코드를 반복하지 않고 의도를 설명하거나 동작을 요약하는가?
  • 의사코드 프로그래밍 과정으로 주석 작성 시간을 줄였는가?
  • 까다로운 코드에 주석만 다는 대신 다시 작성했는가?
  • 주석이 최신 상태인가?
  • 주석이 명확하고 정확한가?
  • 주석 형식이 쉽게 수정할 수 있게 되어 있는가?

문장과 문단

  • 줄 끝 주석을 피했는가?
  • 주석이 방법보다 이유에 초점을 맞추는가?
  • 주석이 뒤에 나올 코드를 독자가 예상하게 하는가?
  • 중복되거나 불필요하거나 자기만족적인 주석을 제거 또는 개선했는가?
  • 뜻밖의 사실을 문서화했는가?
  • 약어를 피했는가?
  • 주요 주석과 부차적 주석의 차이가 분명한가?
  • 오류나 문서화되지 않은 기능을 우회하는 코드에 주석을 달았는가?

데이터 선언

  • 데이터 선언에 단위를 설명했는가?
  • 수치 데이터의 값 범위를 설명했는가?
  • 코드화된 값의 의미를 설명했는가?
  • 입력 데이터의 한계를 설명했는가?
  • 플래그를 비트 수준까지 문서화했는가?
  • 각 전역 변수를 선언 위치에서 설명했는가?
  • 명명 규칙, 주석 또는 둘 다를 사용해 각 사용 지점에서 전역 변수임을 드러냈는가?
  • 매직 넘버를 주석으로만 설명하지 않고 이름 있는 상수나 변수로 바꿨는가?

제어 구조

  • 각 제어문에 목적을 설명하는 주석이 있는가?
  • 길거나 복잡한 제어 구조의 끝을 설명했거나, 주석이 필요 없도록 단순화했는가?

루틴

  • 각 루틴의 목적을 설명했는가?
  • 필요한 경우 입출력 데이터, 인터페이스 가정, 한계, 오류 수정, 전역 효과, 알고리즘 출처를 설명했는가?

파일, 클래스, 프로그램

  • 책 패러다임과 같은 짧은 문서로 프로그램의 전체 구성을 보여 주는가?
  • 각 파일의 목적을 설명했는가?
  • 필요할 경우 책임자의 이름, 이메일 주소, 전화번호를 코드 목록에 포함했는가?

요점 정리

  • 주석을 쓸 것인지는 타당한 질문임. 잘못 작성한 주석은 시간 낭비이거나 해롭지만, 잘 작성한 주석은 가치가 있음.
  • 프로그램의 핵심 정보 대부분은 소스 코드에 있어야 함. 실행되는 동안 계속 관리되는 코드가 다른 문서보다 최신 상태일 가능성이 높음.
  • 좋은 코드는 그 자체가 가장 좋은 문서임. 광범위한 주석이 필요할 정도로 코드가 나쁘다면 먼저 코드부터 개선함.
  • 주석은 코드가 스스로 말할 수 없는 내용을 요약 수준 또는 의도 수준에서 설명해야 함.
  • 번거로운 수작업을 요구하는 주석 형식을 피하고 쉽게 유지할 수 있는 스타일을 사용함.

results matching ""

    No results matching ""