Документирование математической логики в коде

Иногда, хотя и не часто, мне приходится включать математическую логику в мой код. Используемые концепции в основном очень просты, но результирующий код не таков - множество переменных с неясной целью и некоторые операции с не столь очевидным намерением. Я не имею в виду , что код не читается или неосновательный, только что это 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-код полного уравнения в коде - либо это уравнение очень короткое, и размещение tex является грязным и излишним, либо уравнение огромным, а tex-код бесполезен, если вы его не скомпилируете (используйте ссылка вместо). Разбирая уравнение на маленькие части, очень трудно понять, что происходит (по крайней мере, если вы хорошо разбираетесь в математике).

ИМХО, самая важная реализация заключается в том, что формулы часто зависят от контекста. Каждая математическая статья, которую я знаю, требует времени, чтобы настроить среду модели; Вы должны сделать то же самое.

текст не обладает выразительной силой математики

Вы правы. Поскольку вы уже ищете способ сделать это вне кода, и Tex - это слишком много, кроме крутой кривой обучения, я рекомендую следующее:

Используйте OpenOffice.org/LibreOffice Math Equation Editor.

Это бесплатно. Открыто.

Вы можете использовать его визуально или написать уравнения на специальном языке.

Вам не нужно изучать язык сразу, потому что когда вы используете графический интерфейс, на панели генерируется «код», чтобы вы могли его увидеть.

В верхней панели вы можете «нарисовать» уравнения, используя палитру. На нижней панели генерируется эквивалентная запись. Вы можете сделать это наоборот, как только вы освоите нотацию, написав нотацию на нижней панели и увидев графический вывод на верхней панели.