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


19

Иногда, хотя и не часто, мне приходится включать математическую логику в мой код. Используемые концепции в основном очень просты, но результирующий код не таков - множество переменных с неясной целью и некоторые операции с не столь очевидным намерением. Я не имею в виду , что код не читается или неосновательный, только что это Waaaay труднее понять , чем актуальная проблема математики. Я пытаюсь прокомментировать те части, которые сложнее понять, но есть та же проблема, что и при простом их кодировании - текст не обладает выразительной силой математики .

Я ищу более эффективный и простой для понимания способ объяснения логики, лежащей в основе сложного кода, предпочтительно в самом коде. Я рассмотрел TeX - написание документации и создание ее отдельно от кода. Но тогда я должен был бы изучить TeX, и документация не будет в самом коде. Еще одна вещь, о которой я подумал, - сфотографировать математические обозначения, уравнения и диаграммы, написанные на бумаге / доске, и включить их в Javadoc.

Есть ли более простой и понятный способ?



PS Задание описательных имен ( timeOfFirstEventвместо t1) переменных фактически делает код более многословным и еще более сложным для чтения.


5
Изучение TeX на самом деле не так сложно. Если у вас есть код в любом месте, MathJax распечатает его в два раза быстрее. Пожалуйста, помните, что есть такие языки, как HAL / S, где ваши проблемы были отражены давно.
Охотник на оленей

4
Не для моего собственного рога, но вот один пример: meta.stackexchange.com/a/49787/141513 Идея состоит в том, чтобы написать его так, чтобы тот, кто смотрит на него, мог понять, что он делает, даже если он не понимает математика за этим. Для этого обычно достаточно хороших имен функций / переменных и простого комментария или двух.
BlueRaja - Дэнни Пфлугхофт

Ответы:


32

В таких обстоятельствах правильнее всего реализовать алгоритм, формулу или еще что-нибудь с точно такими же именами переменных, что и в первичном реальном источнике (насколько это позволяет язык программирования), и иметь краткий комментарий над ним, говорящий что-то вроде «вычисления расстояния Левенштейна, как описано в [Knuth1968]», где цитата ссылается на легкодоступное описание математики.

(Если вы не имеете такую ссылку, но ваша математика звук и полезно, может быть , вы должны рассмотреть возможность публикации его самостоятельно. Просто говорю.)


4
@JustinC Нет, я думаю, что он имеет в виду те же имена переменных, то есть, если в нем сказано, что y = m*x + cвы используете m, x и c в качестве переменных
jk.

5
@JustinC Я имел в виду: используйте только те переменные и имена констант, которые есть в публикации - обычно это однобуквенные имена, такие как n, f, q или, может быть, n_i. Я согласен с ОП, который EulerLinearMomentumна самом деле менее читабелен m. Дело в том, что исходный код не является предпочтительным средством для выражения формул, поэтому следует сделать упор на упрощение проверки того, что код выполняет то же самое, что и печатная формула, а не то, что код удовлетворяет требованиям программы.
Килиан Фот

1
Я согласен с этой стратегией; однако текст, о котором мы говорим, - это код, код которого имеет базовые ограничения, включая определенную точность / масштаб и поведение (с учетом известного хоста или цели). Вы не определяете или не разрабатываете математическую модель, вы реализуете ее в коде (в большинстве случаев). Без использования собственных имен, которые описывают то, что представлено, гораздо сложнее проверить намерение.
JustinC

2
+1. Если ссылка на недавнюю публикацию, дайте гиперссылку DOI на статью. Пример dx.doi.org/10.1000/182 . Это именно то, для чего был разработан DOI - короткий стандартный URL-адрес для публикации, который гарантированно никогда не изменится.
MarkJ

2
@KeithS полностью зависит для небольшого уравнения, где каждая переменная имеет физический смысл, но что если вы реализуете, скажем, алгоритм БПФ, где будет несколько частичных результатов без физического смысла. В этой ситуации вам абсолютно необходимо соответствовать математической литературе, потому что это язык предметной области
jk.

8

Когда мне приходилось реализовывать подобные алгоритмы, я делаю пару вещей.

  1. Насколько это возможно, выделите алгоритм для его собственного метода или, желательно, класса. Мой текущий проект имеет свой собственный эквивалентный Mathкласс для добавления сложных алгоритмов.

  2. Предоставьте краткое изложение того, что алгоритм должен делать в простейших терминах, включая любые общие сокращения или краткие ссылки на термин. Я делаю это в самом методе, так что он живет с кодом.

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

  4. Документируйте, как я разбил алгоритм на компоненты, и укажите, что каждая переменная представляет в алгоритме. например.t1 is time of first event

  5. Кодируйте алгоритм и комментируйте сложные части. По сути, я добавлю комментарий везде, где я делаю шаг, который не был очевидным или простым в самом алгоритме. Я особенно уверен, что комментирую любые неочевидные ярлыки и почему они в порядке, которые я могу использовать в реализации.

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

Наконец, если это действительно очень-очень сложно, я смиряюсь с тем фактом, что мне принадлежит этот код до конца моего времени в этом проекте.

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


6

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

  1. Предоставьте ссылку на основной источник, который вы используете. Для нас самый простой способ сделать это - использовать BibTex-дескриптор, который в основном является идентификатором для бумаги, которую могут найти все участники. В зависимости от конкретного источника, мы также регулярно добавляем ссылку на уравнение.

  2. Предоставьте объяснения для всех переменных. Опять же, мы используем Tex для этого, если в оригинальной статье используются греческие или другие буквы. Причина этого заключается в том, что достаточно часто в газетах и ​​книгах используются разные обозначения. Если кому-то нужно переделать математику, это делает это намного проще.

  3. Попытайтесь закодировать уравнение в одно целое. Это намного легче распознать. НЕ публикуйте Tex-код полного уравнения в коде - либо это уравнение очень короткое, и размещение tex является грязным и излишним, либо уравнение огромным, а tex-код бесполезен, если вы его не скомпилируете (используйте ссылка вместо). Разбирая уравнение на маленькие части, очень трудно понять, что происходит (по крайней мере, если вы хорошо разбираетесь в математике).

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


1
Детальное объяснение контекста - отличная идея, сосредоточенная на том, «почему», прежде чем «как» может быть действительно полезным.
Jmruc

3

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

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

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

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

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

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

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

введите описание изображения здесь


Тогда что? Включить текстовый код для математической нотации в исходный код в качестве комментариев, или сделать снимок экрана и использовать Javadoc, как сказал OP, что он может сделать с TeX?
dodgethesteamroller

@dodgethesteamroller Да, мой ответ говорит: «Так как вы уже ищете способ сделать это вне кода, а Tex - это излишество…»
Тулаинс Кордова
Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.