Документування математичної логіки в коді

Іноді, хоча і не часто, мені доводиться включати математичну логіку в свій код. Використовувані поняття здебільшого дуже прості, але отриманий код не є - велика кількість змінних з незрозумілим призначенням, а також деякі операції з не настільки очевидним наміром. Я не маю в виду , що код не читається або марна, тільки що це Waaaay важче зрозуміти , ніж актуальна проблема математики. Я намагаюся прокоментувати частини, які найскладніше зрозуміти, але є та сама проблема, що і в простому їх кодуванні - текст не має виразної сили математики .

Я шукаю більш ефективний і простий для розуміння спосіб пояснення логіки деяких складних кодів, бажано в самому коді. Я розглядав TeX - писати документацію та генерувати її окремо від коду. Але тоді мені доведеться вивчити TeX, і документація не буде в самому коді. Ще я подумав - сфотографувати математичні позначення, рівняння та діаграми, написані на папері / дошці, і включити їх у javadoc.

Чи є простіший і зрозуміліший спосіб?

PS Надання описових імен ( timeOfFirstEventзамість t1) змінних насправді робить код більш багатослівним і ще складніше занадто читаним.

Правильно робити за таких обставин - це реалізувати алгоритм, формулу чи будь-що з точно такими ж іменами змінних, що і в первинному джерелі реального світу (наскільки це дозволяє мова програмування), і мати стислий коментар над ним: щось на кшталт "Обчислення відстані Левенштейна, як описано в [Knuth1968]", де цитування посилається на легкодоступний опис математики.

(Якщо ви не маєте таку посилання, але ваша математика звук і корисно, може бути , ви повинні розглянути можливість публікації його самостійно. Просто говорю.)

Коли мені довелося реалізувати такі алгоритми, я роблю пару речей.

1. Наскільки це можливо, виділіть алгоритм до власного методу або бажано класу. Мій поточний проект має власний еквівалентний Mathклас, до якого слід додавати складні алгоритми.

2. Надайте короткий опис того, що алгоритм повинен робити в просторічних формах, включаючи будь-які загальні абревіатури або скорочені посилання на термін. Я роблю це в самому методі, тому він живе з кодом.

3. Надайте зведення алгоритму в технічному / математичному плані та включіть будь-які зовнішні посилання, про які я знаю. Знову ж таки, я це роблю із самим методом, щоб мати більше шансів залишатися актуальними. Звичайний текст у цьому випадку не є великим, тому я навожу математичний термін якнайкраще можу та уточнюю у думці, що поруч із ним. Наприклад, x^y (x raised to the power y)

4. Документуйте, як я розбиваю алгоритм на компоненти, і вкажіть, що кожна змінна репрезентує в алгоритмі. напр.t1 is time of first event

5. Зашифруйте алгоритм і прокоментуйте складні частини. По суті, я додам коментар де завгодно, коли б я зробив крок, який не був очевидним чи прямим у самому алгоритмі. Я особливо переконуюсь, що я коментую будь-які неочевидні ярлики і чому вони нормальні, що я можу взяти під час реалізації.

6. Запишіть кілька одиничних тестів, які підтвердять роботу алгоритму.

Нарешті, якщо це дійсно, справді, дуже складно, то я змирюся з тим, що я володію цим кодом на іншу частину свого часу в цьому проекті.

Мені не подобається покладатися на зовнішній документ, щоб хтось інший зрозумів код. Так, це може знадобитися іноді, особливо, коли потрапляє в таємні деталі. Але коли це можливо, я намагаюся тримати все в самому коді, щоб він мав можливість постійно оновлюватись та легко знаходитись. У цьому випадку я ціную доступність інформації через виразність документації.

У наших проектах, які обертаються навколо досліджень кількісної фінансової економіки, ми використовуємо багато математики і дотримуємось комбінації того, що вже було розміщено:

1. Надайте посилання на основне джерело, яке ви використовуєте. Для нас найпростішим способом зробити це використання ручки BibTex, яка в основному є ідентифікатором для паперу, який можуть шукати всі учасники. Залежно від конкретного джерела, ми також регулярно додаємо посилання рівняння.

2. Надайте пояснення для всіх змінних. Знову ж таки, ми використовуємо Tex для цього, якщо в оригінальному папері використовуються грецькі чи інші літери. Причина цього полягає в тому, що досить часто папери та книги використовують різні позначення. Якщо комусь потрібно переробити математику, це значно спрощує.

3. Спроба кодування рівняння в одній частині. Це набагато легше розпізнати таким чином. НЕ публікуйте Tex-Code повного рівняння в код - або рівняння дуже коротке, і розміщення tex безладно і зайве, або рівняння величезне, а текс-код марний, якщо ви не складете його (Використовуйте a посилання замість цього). Розбирання рівняння на невеликі шматочки робить насправді важко зрозуміти, що відбувається (якщо ти принаймні хороший у математиці).

ІМХО, найважливіше усвідомлення того, що формули часто залежать від контексту. Кожен математичний папір, який я знаю, потребує свого часу, щоб створити середовище моделі; Ви повинні зробити те саме.

текст не має виразної сили математики

Ти правий. Оскільки ви вже шукаєте спосіб зробити це за межами коду, а Tex - це надмірність, крім того, що має круту криву навчання, моя рекомендація полягає в наступному:

Використовуйте OpenOffice.org/LibreOffice Math Equation Editor.

Це безкоштовно. Це відкрито.

Ви можете використовувати його або візуально, або ви можете написати рівняння спеціальною мовою.

Вам не доведеться вивчати мову одразу, тому що, коли ви користуєтесь графічним інтерфейсом, на панелі для вас бачитиметься "код".

На верхній панелі можна "намалювати" рівняння за допомогою піддону. На нижній панелі генерується еквівалентне позначення. Ви можете зробити це навпаки, як тільки ви зрозумієте нотацію, записавши нотацію на нижній панелі та побачивши графічний вихід на верхній панелі.