Tài liệu logic toán học trong mã

Đôi khi, mặc dù không thường xuyên, tôi phải đưa logic toán học vào mã của mình. Các khái niệm được sử dụng hầu hết rất đơn giản, nhưng mã kết quả thì không - rất nhiều biến với mục đích không rõ ràng và một số hoạt động với mục đích không rõ ràng. Tôi không có ý rằng mã không đọc được hoặc unmaintainable, chỉ rằng đó là waaaay khó hiểu hơn so với bài toán thực tế. Tôi cố gắng bình luận những phần khó hiểu nhất, nhưng có một vấn đề tương tự như khi chỉ mã hóa chúng - văn bản không có sức mạnh biểu cảm của toán học .

Tôi đang tìm kiếm một cách hiệu quả và dễ hiểu hơn để giải thích logic đằng sau một số mã phức tạp, tốt nhất là trong chính mã. Tôi đã xem xét TeX - viết tài liệu và tạo nó riêng biệt với mã. Nhưng sau đó tôi phải học TeX và tài liệu sẽ không nằm trong chính mã. Một điều khác tôi nghĩ đến là chụp ảnh các ký hiệu, phương trình và sơ đồ toán học được viết trên giấy / bảng trắng, và bao gồm nó trong javadoc.

Có cách nào đơn giản và rõ ràng hơn không?

PS Việc đặt tên mô tả ( timeOfFirstEventthay vì t1) cho các biến thực sự làm cho mã dài dòng hơn và thậm chí khó đọc hơn.

Các điều đúng đắn nên làm gì trong hoàn cảnh như vậy là để thực hiện các thuật toán, công thức hoặc bất cứ điều gì với chính xác các tên biến giống như trong các nguồn thực tế chính (như xa như các ngôn ngữ lập trình cho phép điều này), và có một lời nhận xét ngắn gọn ở trên nó nói một cái gì đó như "tính toán khoảng cách Levenshtein như được mô tả trong [Knuth1968]", trong đó trích dẫn liên kết đến một mô tả dễ dàng truy cập của toán học.

(Nếu bạn không có tài liệu tham khảo như vậy, nhưng toán học của bạn nghe có vẻ hữu ích, có lẽ bạn nên xem xét việc tự xuất bản nó. Chỉ cần nói.)

Khi tôi phải thực hiện các thuật toán như thế, có một vài điều tôi làm.

1. Càng nhiều càng tốt, cô lập thuật toán theo phương thức riêng của nó hoặc tốt nhất là lớp. Dự án hiện tại của tôi có Mathlớp tương đương của riêng nó để thêm các thuật toán phức tạp vào.

2. Cung cấp một bản tóm tắt về những gì thuật toán được cho là làm theo thuật ngữ lay bao gồm bất kỳ từ viết tắt phổ biến hoặc tham chiếu tốc ký nào cho thuật ngữ này. Tôi làm điều này trong chính phương thức, vì vậy nó sống với mã.

3. Cung cấp một bản tóm tắt của thuật toán bằng thuật ngữ kỹ thuật / toán học và bao gồm bất kỳ tài liệu tham khảo bên ngoài nào mà tôi biết. Một lần nữa, tôi làm điều này với chính phương thức này để nó có cơ hội phù hợp hơn. Văn bản thuần túy không tuyệt vời trong trường hợp này, vì vậy tôi sẽ trích dẫn thuật ngữ toán học tốt nhất có thể và làm rõ trong một nhận xét mang tính cha mẹ bên cạnh nó. Ví dụ, x^y (x raised to the power y)

4. Tài liệu về cách tôi chia thuật toán thành các thành phần và cho biết mỗi biến thể hiện điều gì trong thuật toán. ví dụ.t1 is time of first event

5. Mã lên thuật toán và nhận xét các phần phức tạp. Về cơ bản, tôi sẽ thêm một nhận xét bất cứ nơi nào tôi thực hiện một bước không rõ ràng hoặc đơn giản trong chính thuật toán. Tôi đặc biệt đảm bảo rằng tôi nhận xét bất kỳ phím tắt không rõ ràng nào và tại sao chúng ổn mà tôi có thể thực hiện trong quá trình thực hiện.

6. Viết một số bài kiểm tra đơn vị sẽ xác nhận hoạt động của thuật toán.

Cuối cùng, nếu nó thực sự, thực sự, thực sự phức tạp thì tôi sẽ từ bỏ việc tôi sở hữu mã đó trong phần còn lại của thời gian cho dự án đó.

Tôi không thích dựa vào một tài liệu bên ngoài để người khác hiểu mã. Vâng, đôi khi có thể cần thiết đặc biệt là khi đi vào chi tiết phức tạp. Nhưng bất cứ khi nào có thể, tôi cố gắng giữ mọi thứ trong chính mã để nó có cơ hội được cập nhật và dễ dàng xác định vị trí. Trong trường hợp này, tôi đánh giá cao khả năng tiếp cận thông tin qua tính biểu cảm của tài liệu.

Trong các dự án của chúng tôi, xoay quanh nghiên cứu về kinh tế tài chính định lượng, chúng tôi sử dụng RẤT NHIỀU toán học và chúng tôi tuân theo sự kết hợp của những gì đã được đăng:

1. Cung cấp một liên kết đến nguồn chính bạn đang sử dụng. Đối với chúng tôi, cách dễ nhất để làm điều đó là sử dụng tay cầm BibTex, về cơ bản là ID cho một tờ giấy có thể được tìm kiếm bởi mọi người liên quan. Tùy thuộc vào nguồn cụ thể, chúng tôi thường xuyên thêm tham chiếu phương trình là tốt.

2. Cung cấp giải thích cho tất cả các biến. Một lần nữa, chúng tôi sử dụng Tex cho điều đó nếu bài báo gốc sử dụng tiếng Hy Lạp hoặc các chữ cái khác. Lý do cho điều này là thường có đủ giấy tờ và sách sử dụng các ký hiệu khác nhau. Nếu ai đó cần làm lại toán, điều này làm cho nó dễ dàng hơn nhiều.

3. Cố gắng viết mã phương trình trong một mảnh. Nó dễ dàng hơn nhiều để nhận ra theo cách đó. KHÔNG đăng Mã Tex của phương trình đầy đủ vào mã - hoặc phương trình rất ngắn và việc đăng tex là lộn xộn và không cần thiết, hoặc phương trình rất lớn và mã tex là vô dụng, trừ khi bạn biên dịch nó (Sử dụng một tham khảo thay thế). Việc tách một phương trình thành các phần nhỏ làm cho nó thực sự khó hiểu những gì đang diễn ra (nếu bạn giỏi toán ít nhất).

IMHO, nhận thức quan trọng nhất là các công thức thường phụ thuộc vào ngữ cảnh. Mỗi bài toán tôi biết đều dành thời gian để thiết lập môi trường của mô hình; Bạn nên làm như vậy.

văn bản không có sức mạnh biểu cảm của toán học

Bạn đúng rồi. Vì bạn đã tìm kiếm một cách để làm điều đó bên ngoài mã và Tex là một việc làm quá mức bên cạnh việc có một đường cong học tập dốc, nên đề xuất của tôi như sau:

Sử dụng Trình soạn thảo phương trình toán học OpenOffice.org/LibreOffice.

Nó miễn phí. Nó đang mở.

Bạn có thể sử dụng nó một cách trực quan hoặc bạn có thể viết các phương trình bằng một ngôn ngữ đặc biệt.

Bạn không cần phải học ngôn ngữ ngay lập tức vì khi bạn sử dụng GUI, "mã" được tạo trong một bảng điều khiển để bạn xem.

Trong bảng trên, bạn có thể "vẽ" các phương trình bằng cách sử dụng một pallete. Trong bảng dưới, ký hiệu tương đương được tạo ra. Bạn có thể làm theo cách khác một khi bạn đã nắm được ký hiệu, viết ký hiệu ở bảng dưới và nhìn thấy đầu ra đồ họa ở bảng trên cùng.