코드 문서 : 공개 대 비공개?

나는 작성된 코드가 자명하고 책처럼 읽어야한다는 사고 방식을 가진 개발자 중 하나입니다.

그러나 다른 사람들이 사용할 라이브러리 코드를 개발할 때 가능한 많은 문서를 헤더 파일에 넣으려고합니다. 질문은 비공식적 인 문서화 방법이 시간 가치가 있는가? 그들은 직접 사용할 수는 없지만 실제로는 사용할 수 없습니다. 동시에 원시 코드를 배포하면 (마지 못해도) 공개되지 않은 메소드가 표시되고 설명이 필요할 수 있습니다.

여행 중에 보거나 사용하는 몇 가지 표준과 관행을 찾으십시오.

"최종 사용자"가이를 사용하지 않기 때문에 내부 문서를 생략하는 것을 고려하지 않을 것입니다. 코드 유지 관리는 모든 구성 요소, 특히 가장 복잡하고 자주 변경되는 내부 구성 요소에 대한 문서 주석을 포함해야 할 충분한 이유가됩니다 .

그러나 추상화를 유지하기 위해 헤더가 아닌 소스 코드 (공개적으로 문서화되지 않고)로 제한되도록 유효한 경우가있을 수 있습니다.

이것은 모두 주관적입니다.

좋아, 나는 다양한 방법으로 사진에 주석 달기 / 문서화 방법을 추가합니다. 이유는 헤더에서만 선언 된 함수 또는 멤버 함수를 설명하지 않는 것입니다. 한편으로는 헤더에 너무 많은 노이즈를 추가하는 것이 두렵습니다. 반면에 정의와 함께 문서는 관리자가 쉽게 일치시킬 수 있습니다. Doxygen은 어느 쪽도 신경 쓰지 않으며 필요한 경우 개인을 걸러 낼 수 있습니다.

클래스 헤더에서 :

• 포함 된 헤더 (이유)
• 항상 클래스 정의 (목적 및 책임)
• 항상 순수한 가상 기능 (전체 계약)
• 자명 한 게터가 아닌 한 인라인 함수
• 다른 설명이없는 한 선언 된 다른 유형
• 정적 데이터 멤버 (이유)
• 별도의 설명이없는 한 다른 데이터 멤버
• 매크로가있는 경우 (계약 및 이유)

클래스 구현 코드에서 :

• 헤더와 같은 방식으로 로컬 선언
• 함수 정의 항상 (전체 계약)
• 멤버 함수 정의 항상 (전체 계약 또는 가상 대체 루트에 대한 참조)
• 정적 변수가있는 경우 정의 됨 (목적 이유)

템플릿 헤더에서 :

• 위의 합병
• 템플릿 인수에 적합하거나 적합하지 않은 유형
• 적합성이 정적으로 얼마나 잘 감지되는지

private:민간 부분의 시작 부분은 사용자가 필요로해야 모든 문서입니다.

문서는 그 어느 때보 다 가치가 있으며 사용 사례와 사례를 간단한 방식으로 설명하는 데 도움이됩니다. 코드가 어느 정도 설명이 필요한지에 대해서는 몇 줄의 스토리를 말하는 것처럼 쉽게 비즈니스를 설명 할 수 없습니다. 이 코드는 사용자에게 진행 상황을 이해하고 논리를 따라야합니다. :-) 내 2 센트 ...

명확히!

이 코드는 자체 문서화가되어야합니다. 그러나 개인 코드는 공개 코드보다 많은 문서가 필요하지만, 대부분의 가정은 일반적으로 코더가 어둠 속에 남아 있다고 가정하기 때문에 대부분의 가정이 이루어지기 때문입니다. . 따라서 몇 달 후, 버그가 발생하면 코드 뒤에 아이디어가 무엇인지 기억하려고 노력할 것입니다.

다른 사람들에게 좋은 선물로 문서가 없어서는 안됩니다. 모든면에서 문서 (잘 선택된 변수 이름, 자체 문서화 클래스 이름, 잘 구성된 코드, 올바르게 분할 된 메소드 등)는 코드와 접촉 할 수있는 모든 사람에게 자신이 포함 된 선물입니다.