과학 소프트웨어를 문서화하는 좋은 방법은 무엇입니까?

많은 사람들이 다른 사람들이 작성한 과학 코드를 물려 받았을 때 (또는 때로는 내 자신의 작업조차도) 문서가 드물거나 존재하지 않는 것을 발견했습니다. 운이 좋으면 유익한 의견이 표시됩니다. 운이 좋으면 Doxygen 주석과 Doxyfile도있어서 함수 인터페이스와 형식이 지정된 HTML을 참조하십시오. 운이 좋으면 Doxygen 및 소스 파일 주석 외에도 PDF 설명서와 예제가 있으며 내 인생을 훨씬 쉽게 만들어주기 때문에 황홀합니다.

소스 코드를 문서화하는 데 유용한 정보와 도구는 무엇입니까? 과학 소프트웨어의 경우 해당 소스 코드와 함께 제공되는 데이터와 결과를 문서화하는 데 유용한 정보와 도구는 무엇입니까?

과학 소프트웨어에 대한 문서는 세 가지 범주로 나눌 수 있으며,이 범주는 모두 완전히 이해하는 데 필요합니다. 가장 쉽고 가장 일반적인 방법은 개별 분석법 문서입니다. 이를위한 많은 시스템이 있습니다. 당신은 doxygen을 언급하고 , 파이썬은 pydoc을 가지고 있으며 , PETSc 에는 다음 을 생성하는 우리 자신의 패키지 파종 이 있습니다.

그러나 간단한 유틸리티 이상의 소프트웨어는 매뉴얼이 필요합니다. 이것은 패키지의 목적에 대한 높은 수준의 관점과 다양한 기능이이 목적을 달성하기 위해 어떻게 통합되는지를 제공합니다. 새로운 사용자가 종종 예제를 사용하여 코드를 구성하는 데 도움이됩니다. PETSc에서는 매뉴얼에 LaTeX를 사용하지만 PyClaw 패키지는 내가 감명받은 Sphinx 프레임 워크를 사용합니다 . 매우 유용한 파종 패키지에서 구현 한 한 가지 예는 예제 코드와 함수 설명서 간의 링크입니다. 예를 들어이 예는Bratu 방정식을 해결합니다. 사용자 정의 유형 또는 함수 호출에 대한 링크를 따라 하위 레벨 문서로 이동하는 방법과 해당 페이지를 사용하여 해당 페이지를 다시 링크하는 방법에 주목하십시오. 이것이 프로젝트의 다른 사람들이 제공하는 새로운 기능에 대해 배우는 방법입니다.

제 생각에 자주 간과되는 부분은 개발자 문서입니다. 코딩 스타일 문서와 리포지토리와의 상호 작용에 대한 지침을 게시하는 것은 드문 일이 아닙니다. 그러나 구현 전에 내려진 설계 결정을 설명하는 것은 매우 드 rare니다. 이러한 결정에는 항상 트레이드 오프가 수반되며 하드웨어 및 알고리즘과 관련된 상황은 시간이 지남에 따라 변경 될 수 있습니다. 특정 설계 결정에 대한 검토 및 이론적 근거에 대한 논의없이, 이후의 프로그래머는 전체 프로세스를 스스로 재 작성해야합니다. 원래 개발자가 더 이상 책임을지지 않을 때 이것이 오래된 코드를 성공적으로 유지 관리하고 개선하는 데 큰 걸림돌이라고 생각합니다.

코드 내 문서

가장 중요한 것은 선택한 개발 환경에서 문서 기능을 사용하는 것입니다. 따라서 파이썬 용 pydoc , java의 javadoc 또는 C #의 xml 주석 을 의미합니다. 이를 통해 코드 작성과 동시에 문서를 쉽게 작성할 수 있습니다.

나중에 돌아와서 문서를 작성하는 데 의존한다면, 그 문제를 해결하지 못할 수도 있지만 코드를 작성하면서 코드를 작성하면 문서화해야 할 것이 마음에 새겨질 것입니다. C #에는 XML 문서가 불완전하거나 실제 코드와 일치하지 않는 경우 컴파일 경고를 발행 할 수도 있습니다.

문서로 테스트

또 다른 중요한 측면은 통합 및 단위 테스트가 우수하다는 것입니다.

종종 문서는 클래스와 메소드가 독립적으로 수행하는 작업에 중점을 두어 문제 해결을 위해 함께 사용되는 방법을 건너 뜁니다. 테스트는 종종 서로 상호 작용하는 방식을 보여줌으로써 상황에 맞게 배치합니다.

유사하게, 단위 테스트는 종종 외부 의존성을 지적하여 어떤 것들을 모의해야하는지 명시 적으로 지적합니다.

또한 테스트 중심 개발 을 사용하면 go라는 단어에서 바로 사용하기 때문에 사용하기 쉬운 소프트웨어를 작성 한다는 것을 알았습니다. 좋은 테스트 프레임 워크를 사용하면 코드를 쉽게 테스트하고 사용하기 쉽게 만드는 것이 종종 같은 일입니다.

더 높은 수준의 문서

마지막으로 시스템 레벨 및 아키텍처 문서에 대해 수행 할 작업이 있습니다. 많은 사람들이 위키에서 문서를 작성하거나 Word 또는 다른 워드 프로세서를 사용하는 것을 주창 할 것이지만, 나에게 그러한 문서를위한 가장 좋은 장소는 코드와 함께 버전 관리 시스템 친화적 인 일반 텍스트 형식입니다.

코드 내 문서와 마찬가지로 상위 수준의 문서를 코드 저장소에 저장하면 최신 상태로 유지할 가능성이 높습니다. 또한 코드의 버전 XY를 가져올 때 설명서의 버전 XY도 얻을 수 있다는 이점이 있습니다. 또한 VCS 친화적 형식을 사용하면 코드와 마찬가지로 문서를 쉽게 분기, 확산 및 병합 할 수 있습니다.

sphinx를 사용하여 html 페이지와 pdf 문서를 쉽게 생성 할 수 있고 LaTeX 보다 훨씬 친숙 하지만 필요한 경우 여전히 LaTeX 수학 표현식을 포함 할 수 있기 때문에 reStructuredText (first)를 매우 좋아 합니다.

나는 Faheem이 만드는 거의 모든 점에 대해 이의를 제기 할 것 입니다. 구체적으로 :

1 / "과학 개발자가 소프트웨어를 문서화하는데 많은 시간을 할애하는 것은 비현실적이라고 생각합니다." 실패한 프로젝트에 대한 처방으로 곧 주요 개발자에게 접근 권한이없는 사람은 누구도 사용할 수 없게됩니다. 큰 과학 컴퓨팅 라이브러리 (예 : PETSc 또는 deal.II)에 1,000 페이지 이상의 페이지가 포함 된 광범위한 문서가 있기 때문입니다. 광범위한 문서가 없으면 상당한 사용자 커뮤니티를 가질 수 없습니다. 그러나 예제 코드는 단순해야하며 단일 개념에 중점을 두어야한다는 데 동의합니다.

2 / "필요한 경우 저자는 출판을위한 논문 작성을 고려해야합니다". 실제로는 불가능합니다. 개념과 알고리즘에 대해서는 논문을 작성할 수 있지만 인터페이스 및 기타 디자인 결정에 대해서는 논문을 작성할 수 없습니다. 그러한 논문의 독자들은 구현이 무엇을하는지에 대한 아이디어를 얻게 될 것입니다. 구현의 사용자는 호출 할 함수, 인수의 의미 등을 알아야합니다. 사용자는 대부분 전자 없이도 살 수 있고 라이브러리를 블랙 박스로 간주하지만 인터페이스 정보.

좋은 질문입니다. 첫 번째 근사치로, 코드는 자체 문서화를 시도해야합니다. 소프트웨어가 명령 줄을 경우 그래서, 예를 들어, 당신은 할 수 있어야 executable --help하거나 executable -h또는 executable(실행 인수없이 아무것도하지 않는 경우), 그리고 간단한 사용법 메시지 리턴이있다.

둘째, 과학 개발자가 소프트웨어를 문서화하는 데 많은 시간을 할애하는 것은 비현실적이라고 생각하므로 간단하게 유지하는 것이 좋습니다. 기본 방법 및 옵션과 주석이 달린 작업 및 테스트를 포함한 간단한 텍스트 매뉴얼사용 예제는 단순에서 더 복잡한 것으로 사용됩니다 (사용 예제는 매우 중요하고 자주 무시 됨). 또한 사용 예제에 대해 애완 동물을 추가하고 싶습니다. 단순은 단순함을 의미합니다. 즉, 분석법을 설명하려는 경우 독자를 혼란스럽게하는 10 가지 외부 개념이나 방법을 추가하지 않아도됩니다. 독자가 예제가 무엇을해야하는지 알 수 있도록 간단하고 주석을 달아 두십시오. 또한 수동 사용법 예제를 테스트 스위트에 묶어 코드가 변경 될 때 계속 작동하도록 제안합니다. 나는 실제로 좋은 방법으로 이것을하는 방법을 모른다. 그래서 나에게 교육을 주시기 바랍니다. 개발자가 더 화려하게 만들고 싶다면 멋진 마크 업 언어 등을 사용할 수 있는지 확인하고 매뉴얼 페이지 등을 추가하십시오.

셋째, 저자는 적절한 경우 출판 용 논문 작성을 고려해야합니다. 이것은 일반적으로 설계 결정을 다루고 매뉴얼보다 더 높은 수준의 소프트웨어 관점을 제공합니다. 이것은 @Matt가 말한 디자인 결정의 문서화를 다룰 것입니다.

물론, 가장 중요한 문서는 코드 자체이며 필요에 따라 주석을 달아야합니다. 이것은 코드가 자유 소프트웨어라고 가정합니다. 그렇지 않은 경우 과학 소프트웨어만큼 유용하지 않습니다 (메서드가 어떻게 구현되는지 볼 수없는 블랙 박스를 사용하고 싶습니까?). 나는 그것을 사용하지 않을 것입니다.

데이터와 결과를 문서화하는 방법에 대한 귀하의 질문을 해결하기 위해 Python의 doctest module 과 같은 것이 좋습니다 . 이를 통해 자동으로 확인할 수있는 방식으로 자습서 또는 테스트를 작성할 수 있습니다.

문맹 프로그래밍에 관심이 있다면 org-babel을 살펴보십시오 . Emacs에서 org-mode의 일부이므로 문서화를위한 다양한 내보내기 옵션 (LaTeX, PDF, HTML, ODT)을 제공합니다. 이맥스는 버퍼 안에 이미지를 표시 할 수 있으며 LaTeX 구문으로 수학 방정식을 작성할 수 있으므로 일반 텍스트 문서로 제한 할 필요가 없습니다.

소스 코드에서 자동으로 파생 된 설명서는 최신 설명서 (예 : 올바른 설명서)를 갖추기위한 필수 구성 요소입니다. 문서화에 대한 개발자의 무관심으로 인해 소스 코드보다 몇 년 이 지난 문서를 몇 번이나 본 적이 있는지 셀 수 없습니다 . 쉬운 해결책은 프로그래머가보다 영광스러운 활동에 유리하게 우선 순위를 잃게되는 사소한 노력이 아니라 같은 장소에서 새로운 코드와 함께 문서를 쉽게 작성할 수 있도록하는 것입니다.

강제로 선택한다면, 상세하고 정확한 (즉, 현재의) 소스 코드 주석이 있지만 잘못된 정보로 가득 찬 오래된 사용자 매뉴얼보다 사용자 매뉴얼이 없습니다 .

파이썬에는 pep8 및 pep257 도구가 있는데,이 도구는 누락되거나 잘못된 문서를보고합니다. Emacs 용 elpy는 누락 된 문서에 대해 불평합니다. 규칙을 문서화 문자열 NumPy와 reStructuredText으로는 따라하기 좋다. pep8, pep257 및 doctest로 테스트하면 py.test 및 tox가 자동으로 실행되도록 설정할 수 있습니다.