Những cách tốt để tài liệu phần mềm khoa học là gì?

Nhiều lần, khi tôi được thừa hưởng hoặc gặp phải mã khoa học được viết bởi người khác (hoặc đôi khi, ngay cả công việc của riêng tôi), tôi đã nhận thấy rằng tài liệu là thưa thớt hoặc không tồn tại. Nếu tôi may mắn, tôi thấy những bình luận đầy thông tin. Nếu tôi rất may mắn, thậm chí còn có các bình luận Doxygen và Doxyfile để tôi có các giao diện chức năng và một số HTML được định dạng để tham khảo. Nếu tôi cực kỳ may mắn, có một hướng dẫn sử dụng PDF và các ví dụ cùng với các nhận xét về tệp nguồn và Doxygen, và tôi ngây ngất, vì nó giúp cuộc sống của tôi dễ dàng hơn nhiều.

Thông tin và công cụ nào hữu ích trong việc ghi lại mã nguồn? Đối với vấn đề đó, thông tin và công cụ nào hữu ích để ghi lại dữ liệu và kết quả đi kèm với mã nguồn đó, trong trường hợp phần mềm khoa học?

Tôi nghĩ rằng tài liệu cho phần mềm khoa học có thể được chia thành ba loại, tất cả đều cần thiết cho sự hiểu biết đầy đủ. Đơn giản nhất và phổ biến nhất là tài liệu phương pháp cá nhân. Có nhiều hệ thống cho việc này. Bạn đề cập đến doxygen , Python có pydoc và trong PETSc chúng tôi có gói gieo riêng của chúng tôi tạo ra các mục sau .

Tuy nhiên, đối với bất kỳ phần mềm nào vượt ra ngoài một tiện ích đơn giản, bạn cần có hướng dẫn sử dụng. Điều này cung cấp một cái nhìn cấp cao về mục đích của gói và cách các chức năng khác nhau của nó tích hợp để đạt được mục đích này. Nó giúp người dùng mới cấu trúc mã của họ, thường thông qua việc sử dụng các ví dụ. Trong PETSc, chúng tôi chỉ sử dụng LaTeX cho hướng dẫn, nhưng gói PyClaw sử dụng khung Sphinx mà tôi rất ấn tượng. Một điều mà chúng tôi đã thực hiện trong gói gieo mà tôi thấy rất hữu ích là liên kết giữa mã ví dụ và tài liệu hàm. Ví dụ, ví dụ nàygiải phương trình Bratu. Lưu ý cách bạn có thể theo các liên kết cho bất kỳ cuộc gọi tùy chỉnh hoặc loại chức năng nào và đến tài liệu cấp thấp và cách các trang đó liên kết lại với các ví dụ sử dụng chúng. Đây là cách tôi tìm hiểu về chức năng mới mà những người khác trong dự án đóng góp.

Một phần thường xuyên bị bỏ qua của tài liệu, tôi nghĩ, là tài liệu dành cho nhà phát triển. Không có gì lạ khi xuất bản một tài liệu theo kiểu mã hóa và các hướng dẫn để tương tác với kho lưu trữ. Tuy nhiên, rất hiếm khi giải thích các quyết định thiết kế được đưa ra trước khi thực hiện. Những quyết định này luôn liên quan đến sự đánh đổi, và tình hình liên quan đến phần cứng và thuật toán sẽ nhất thiết phải thay đổi theo thời gian. Không có một cuộc thảo luận về sự đánh đổi được xem xét và lý do cho các quyết định thiết kế cụ thể, các lập trình viên sau đó sẽ tự mình tạo lại toàn bộ quá trình. Tôi nghĩ rằng đây là một trở ngại lớn cho việc bảo trì và cải thiện mã cũ thành công khi các nhà phát triển ban đầu không còn phụ trách.

Tài liệu trong mã

Điều quan trọng nhất là sử dụng các phương tiện tài liệu trong môi trường phát triển đã chọn của bạn, điều đó có nghĩa là pydoc cho python, javadoc trong các bình luận java hoặc xml trong C #. Điều này làm cho nó dễ dàng để viết tài liệu cùng lúc với việc viết mã.

Nếu bạn dựa vào việc quay lại và ghi lại những điều sau đó, bạn có thể không nhận được nó, nhưng nếu bạn làm điều đó khi bạn đang viết mã, thì những gì cần được ghi lại sẽ rất mới mẻ trong tâm trí bạn. C # thậm chí có tùy chọn đưa ra cảnh báo biên dịch nếu tài liệu XML không đầy đủ hoặc không phù hợp với mã thực tế.

Các xét nghiệm như tài liệu

Một khía cạnh quan trọng khác là có tích hợp tốt và kiểm tra đơn vị.

Thông thường tài liệu tập trung vào những gì các lớp và phương thức làm riêng rẽ, bỏ qua cách chúng được sử dụng cùng nhau để giải quyết vấn đề của bạn. Các thử nghiệm thường đặt những điều này vào bối cảnh bằng cách hiển thị cách chúng tương tác với nhau.

Tương tự, các bài kiểm tra đơn vị thường chỉ ra các phụ thuộc bên ngoài một cách rõ ràng thông qua đó mọi thứ cần được Mock ed out.

Tôi cũng thấy rằng sử dụng phần mềm phát triển dựa trên thử nghiệm, tôi viết phần mềm dễ sử dụng hơn, bởi vì tôi đang sử dụng nó ngay từ đầu. Với một khung kiểm tra tốt, làm cho mã dễ kiểm tra hơn và làm cho nó dễ sử dụng thường là điều tương tự.

Tài liệu cấp cao hơn

Cuối cùng, có những gì để làm về cấp độ hệ thống và tài liệu kiến ​​trúc. Nhiều người sẽ ủng hộ việc viết tài liệu đó trong wiki hoặc sử dụng Word hoặc trình xử lý văn bản khác, nhưng đối với tôi, nơi tốt nhất cho tài liệu đó là bên cạnh mã, trong một định dạng văn bản đơn giản, thân thiện với hệ thống kiểm soát phiên bản.

Giống như với tài liệu trong mã, nếu bạn lưu trữ tài liệu cấp cao hơn trong kho lưu trữ mã của mình thì bạn có nhiều khả năng sẽ cập nhật nó. Bạn cũng nhận được lợi ích là khi bạn rút phiên bản XY của mã, bạn cũng nhận được phiên bản XY của tài liệu. Ngoài ra, nếu bạn sử dụng định dạng thân thiện với VCS, điều đó có nghĩa là nó dễ dàng phân nhánh, tìm khác biệt và hợp nhất tài liệu của bạn, giống như mã của bạn.

Tôi khá thích reSturationuredText (rst) , vì nó dễ dàng tạo ra cả trang html và tài liệu pdf từ nó bằng sphinx , và thân thiện hơn LaTeX , nhưng vẫn có thể bao gồm các biểu thức toán học LaTeX khi bạn cần.

Tôi sẽ phản đối với hầu hết mọi điểm mà Faheem đưa ra . Đặc biệt:

1 / "Tôi nghĩ rằng việc các nhà phát triển khoa học dành nhiều thời gian để làm tài liệu cho phần mềm của họ là không thực tế". Đây là một đơn thuốc cho một dự án thất bại mà sẽ sớm không ai có thể sử dụng những người không có quyền truy cập vào các nhà phát triển chính. Đó là lý do chính đáng để các thư viện máy tính khoa học lớn (ví dụ: PETSc, hoặc deal.II) có tài liệu mở rộng chạy vào 1.000 trang trở lên. Bạn không thể có một cộng đồng người dùng khá lớn nếu bạn không có tài liệu phong phú. Tôi sẽ đồng ý, tuy nhiên, các mã ví dụ cần phải đơn giản và tập trung vào một khái niệm duy nhất.

2 / "các tác giả nên xem xét viết một bài báo để xuất bản nếu thích hợp". Điều đó thường không thể thực hiện được trong thực tế. Người ta có thể viết các bài báo về các khái niệm và thuật toán, nhưng không phải trên giao diện và các quyết định thiết kế khác. Người đọc các bài viết như vậy sẽ có được một ý tưởng về việc thực hiện nó; Người dùng thực hiện sẽ cần biết chức năng nào để gọi, ý nghĩa của các đối số, v.v. Là người dùng, hầu hết mọi người có thể sống mà không cần trước đây và chỉ đơn giản coi thư viện là hộp đen, nhưng người ta không thể làm mà không có thông tin giao diện.

Đây là một câu hỏi hay. Đến một xấp xỉ đầu tiên, mã nên cố gắng tự ghi lại. Vì vậy, ví dụ, nếu phần mềm là dòng lệnh, bạn sẽ có thể làm executable --helphoặc executable -hhoặc thậm chí executable(nếu thực thi không có gì không có đối số), và có một sự trở lại thông điệp sử dụng ngắn.

Thứ hai, tôi nghĩ rằng việc các nhà phát triển khoa học dành nhiều thời gian để làm tài liệu cho phần mềm của họ là không thực tế, vì vậy tôi khuyên bạn nên giữ nó đơn giản. Một hướng dẫn văn bản ngắn với các phương pháp và tùy chọn cơ bản và làm việc và kiểm tra chú thíchcác ví dụ về việc sử dụng, được chuyển từ đơn giản đến phức tạp hơn (ví dụ về sử dụng rất quan trọng và thường xuyên bị bỏ qua) tốt hơn đáng kể so với không có gì và nhiều hơn hầu hết các phần mềm khoa học cung cấp. Tôi cũng muốn thêm một tiểu thú cưng về các ví dụ sử dụng. Đơn giản có nghĩa là đơn giản. Điều đó có nghĩa là nếu bạn đang cố gắng minh họa một phương thức, bạn không thêm vào mười khái niệm hoặc phương thức không liên quan để gây nhầm lẫn cho người đọc. Giữ cho nó đơn giản và chú thích để người đọc biết ví dụ được cho là đang làm gì. Tôi cũng đề nghị buộc các ví dụ sử dụng thủ công vào bộ kiểm tra bằng cách nào đó để chúng tiếp tục hoạt động khi mã được thay đổi. Tôi thực sự không biết làm thế nào để làm điều này một cách tốt đẹp, vì vậy xin vui lòng giáo dục tôi. Nếu các nhà phát triển muốn trở nên lạ mắt hơn, chắc chắn rằng họ có thể sử dụng các ngôn ngữ đánh dấu đẹp và vv, hãy thêm các trang hướng dẫn, v.v.

Thứ ba, các tác giả nên xem xét viết một bài báo để xuất bản nếu thích hợp. Điều này thường sẽ giải quyết các quyết định thiết kế và đưa ra một viễn cảnh cao hơn về phần mềm so với hướng dẫn sử dụng, hoặc có thể được dự kiến ​​sẽ làm. Điều này sẽ giải quyết các tài liệu về các quyết định thiết kế mà @Matt đang nói đến.

Tất nhiên, tài liệu quan trọng nhất của tất cả là mã, cần được nhận xét khi cần thiết. Điều này giả sử mã là phần mềm miễn phí. Nếu không, thì nó thực sự ít hữu ích như phần mềm khoa học (bạn có thực sự muốn sử dụng hộp đen trong đó bạn không thể thấy các phương thức được triển khai như thế nào không?) Và tôi sẽ không sử dụng nó.

Để giải quyết câu hỏi của bạn về cách ghi lại dữ liệu và kết quả, tôi khuyên bạn nên sử dụng mô-đun doctest của Python . Điều này cho phép bạn viết hướng dẫn hoặc kiểm tra theo cách có thể được xác nhận tự động.

Nếu bạn quan tâm đến lập trình biết chữ, hãy xem org-babel . Nó là một phần của chế độ org trong Emacs và do đó cung cấp cho bạn một loạt các tùy chọn xuất (LaTeX, PDF, HTML, ODT) cho tài liệu. Emacs có thể hiển thị hình ảnh bên trong bộ đệm và cho phép bạn viết các phương trình toán học theo cú pháp LaTeX để bạn không phải giới hạn bản thân trong tài liệu văn bản thuần túy.

Tài liệu được tự động lấy từ mã nguồn của bạn là một thành phần thiết yếu trong việc cập nhật tức là tài liệu chính xác. Tôi không thể đếm được bao nhiêu lần tôi đã xem tài liệu chậm hơn mã nguồn nhiều năm vì sự thờ ơ của nhà phát triển đối với tài liệu. Giải pháp dễ dàng là giúp các lập trình viên dễ dàng viết tài liệu cùng với mã mới ở cùng một nơi thay vì một nỗ lực sau này chắc chắn sẽ được ưu tiên hơn trong các hoạt động vinh quang hơn.

Nếu buộc phải chọn, tôi muốn có các nhận xét mã nguồn chi tiết và chính xác (hiện tại) nhưng không có hướng dẫn sử dụng nào ngoài hướng dẫn sử dụng đã lỗi thời có đầy đủ thông tin sai.

Trong Python có các công cụ pep8 và pep257 sẽ báo cáo tài liệu bị thiếu hoặc không đúng định dạng. elpy cho Emacs cũng sẽ phàn nàn về tài liệu bị thiếu. Các quy ước chuỗi Numpy với reSturationuredText là tốt để tuân theo. Kiểm tra với pep8, pep257 và doctest có thể được thiết lập với py.test và độc tố chạy tự động.