Một lập trình viên nên giải thích logic mở rộng đằng sau mã?

Tôi đã phát triển một vài thư viện định lượng trong C #, điều quan trọng là không chỉ hiểu thông tin cổ điển đi kèm với các nhận xét XMLDoc (chứa thông tin cơ bản với chữ ký phương thức) mà cả các công thức toán học đang được sử dụng trong các phương thức.

Do đó, tôi muốn có thể bao gồm tài liệu mở rộng với mã, có thể chứa, ví dụ như công thức latex, đồ thị, v.v.

Bạn có nghĩ rằng thông tin đó nên được đưa vào tài liệu API không?

Hoặc nó nên được đưa vào một blog dev cho các ví dụ?

Có những công cụ phổ biến thường được sử dụng cho loại mục đích này không?

Theo như tôi quan tâm, bạn càng giữ tài liệu về mã càng gần thì càng có khả năng được cập nhật và nó càng hữu ích hơn.

Đó là lý do tại sao tôi cố gắng giữ tất cả tài liệu trong cùng một kho lưu trữ như mã, thậm chí hướng dẫn sử dụng và cố gắng giữ nó ở định dạng văn bản đơn giản có thể dễ dàng quản lý bằng hệ thống kiểm soát sửa đổi.

Tài liệu trong mã

Có vẻ như bạn đã có cái này, nhưng điều quan trọng cần nhớ là thực sự 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 ( pydoc cho python, javadoc trong java hoặc xml bình luận trong C #) là kỹ thuật tài liệu quan trọng nhất. Chúng giúp bạn dễ dàng viết tài liệu cùng lúc với 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 thực hiện một cách cô lập, 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 chúng 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 thử 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ì cần làm về cấp độ hệ thống, kiến ​​trúc, nhà phát triển và có thể cả tài liệu người dùng cuối. 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 đó cũng nằm bên cạnh mã, ở đị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, giống như mã của bạn.

Tôi khá thích đầu tiên , vì nó dễ dàng tạo ra cả trang html và tài liệu pdf từ nó, 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 chúng.

Khi viết mã toán học cao, tôi cũng thấy hữu ích khi có một vài tài liệu wxmaxima trong kho dự án của tôi. Là văn bản đơn giản, chúng cũng phân nhánh, khác biệt và hợp nhất độc đáo, nhưng sử dụng hệ thống đại số máy tính có thể giúp bạn kiểm tra tính nhất quán của công thức cũng như ghi lại chúng.

Bạn có thể bao gồm tài liệu đó trong các nhận xét XML và tạo hướng dẫn sử dụng LaTeX, trang web và các tài liệu khác từ đó bằng cách sử dụng doxygen . Sử dụng các yếu tố <remarks>và <example>cho văn xuôi mở rộng.

Tôi sẽ sử dụng tài liệu bên ngoài nếu bạn cần bao gồm các sơ đồ lớp, đồ thị, công thức, hình ảnh, v.v. để giải thích cách thư viện của bạn hoạt động. Bao gồm tài liệu bên ngoài này như một phần của bản phát hành thư viện của bạn ở bất kỳ định dạng nào bạn cho là phù hợp (LaTeX hoặc cách khác). Bạn có thể tham khảo tài liệu này từ mã của mình nếu muốn (ví dụ: "Xem tài liệu" Readme "để biết thêm thông tin.").

Chìa khóa, tôi tin, là sự nhất quán . Nếu bạn đã liên tục chú thích các phương thức với các nhận xét có thể được trích xuất bằng ví dụ Doxygen, thì việc đưa vào mô tả logic mở rộng cũng có ý nghĩa vì đó là nơi mà các nhà phát triển đồng nghiệp có thể nhìn vào. Đột nhiên chỉ nhà phát triển đến một số tài liệu khác có vẻ không cần thiết và sẽ chỉ gây nhầm lẫn cho các nhà phát triển.

Tuy nhiên, nếu mô tả của toàn bộ chương trình được đưa ra ở nơi khác, thì bạn nên gắn bó với điều đó và đưa ra mô tả logic mở rộng ở đó.

Nếu bạn cảm thấy cần phải ghi lại các phần bên trong của một phương thức trong API của mình, thì có lẽ bạn chưa xác định / mô đun hóa giao diện rất tốt.

API được viết tốt không nên BẮT BUỘC lập trình viên để hiểu cách thức hoạt động của bên trong. Ngoài ra, bằng cách ghi lại một cách không cần thiết cách thức hoạt động, bạn đang phá vỡ lớp trừu tượng và tự khóa mình vào một triển khai cụ thể, điều này cũng không tốt.