Каковы хорошие способы документирования научного программного обеспечения?

Много раз, когда я унаследовал или столкнулся с научным кодом, написанным другими людьми (или, иногда, даже с моей собственной работой), я заметил, что документация либо недостаточна, либо вообще отсутствует. Если мне повезет, я вижу информативные комментарии. Если мне очень повезет, есть даже комментарии Doxygen и Doxyfile, так что у меня есть функциональные интерфейсы и некоторый форматированный HTML для консультации. Если мне очень повезет, есть руководство в формате PDF и примеры в дополнение к комментариям к Doxygen и исходному файлу, и я в восторге, потому что это делает мою жизнь намного, намного проще.

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

Я думаю, что документацию для научного программного обеспечения можно разделить на три категории, которые необходимы для полного понимания. Самым простым и распространенным является документация по отдельным методам. Для этого есть много систем. Вы упоминаете doxygen , в Python есть pydoc , а в PETSc у нас есть собственный посев пакетов, который генерирует следующее .

Однако для любого программного обеспечения, выходящего за рамки простой утилиты, вам необходимо руководство. Это обеспечивает общее представление о назначении пакета и о том, как его различные функции интегрируются для достижения этой цели. Это помогает новому пользователю структурировать свой код, часто с помощью примеров. В PETSc мы просто используем LaTeX для руководства, но пакет PyClaw использует инфраструктуру Sphinx, которая меня очень впечатлила. Одна вещь, которую мы реализовали в посевном пакете, и которую я считаю очень полезной, это связь между примером кода и документацией функций. Например, этот примеррешает уравнение Брату. Обратите внимание, как вы можете переходить по ссылкам для вызова любого пользовательского типа или функции и получать доступ к документации низкого уровня, и как эти страницы ссылаются на примеры с их использованием. Так я узнаю о новой функциональности, которую вносят другие участники проекта.

Я думаю, что часто пропускаемой частью документации является документация для разработчиков. Нередко публикуются документ в стиле кодирования и инструкции по взаимодействию с хранилищем. Однако очень редко можно объяснить проектные решения, принятые до реализации. Эти решения всегда включают компромиссы, и ситуация с аппаратными средствами и алгоритмами обязательно изменится со временем. Без обсуждения рассмотренных компромиссов и обоснования конкретных проектных решений последующим программистам остается воссоздавать весь процесс самостоятельно. Я думаю, что это является серьезным препятствием для успешного обслуживания и улучшения старых кодов, когда первоначальные разработчики больше не отвечают.

Документация в коде

Самое главное - использовать средства документации в выбранной вами среде разработки, что означает pydoc для python, javadoc в java или xml комментарии в C #. Это облегчает написание документации одновременно с написанием кода.

Если вы полагаетесь на то, что вернетесь и документируете вещи позже, вы, возможно, не сможете обойти это, но если вы сделаете это, когда пишете код, то то, что нужно документировать, будет свежим в вашем уме. C # даже имеет возможность выдать предупреждение компиляции, если документация XML неполна или не соответствует реальному коду.

Тесты как документация

Другим важным аспектом является хорошая интеграция и модульные тесты.

Часто документация сосредотачивается на том, что классы и методы делают изолированно, пропуская, как они используются вместе, чтобы решить вашу проблему. Тесты часто помещают их в контекст, показывая, как они взаимодействуют друг с другом.

Точно так же модульные тесты часто явно указывают на внешние зависимости, через которые нужно что-то исключать .

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

Документация высшего уровня

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

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

Мне очень нравится reStructuredText (rst) , поскольку из него легко создавать html-страницы и pdf-документы с использованием sphinx , и он намного удобнее, чем LaTeX , но все же может включать математические выражения LaTeX, когда они вам нужны.

Я возражу против почти всех высказываний Фахима . В частности:

1 / «Я думаю, что нереально ожидать, что научные разработчики будут тратить много времени на документирование своего программного обеспечения». Это рецепт неудачного проекта, который скоро никто не сможет использовать, у которого нет доступа к основным разработчикам. По понятной причине крупные научные вычислительные библиотеки (например, PETSc или deal.II) имеют обширную документацию, которая занимает тысячи страниц и более. У вас не может быть значительного сообщества пользователей, если у вас нет обширной документации. Я согласен, однако, что примеры кодов должны быть простыми и сфокусированными на одной концепции.

2 / «авторам следует рассмотреть возможность написания статьи для публикации, если это уместно». Это часто невозможно на практике. Можно писать статьи о концепциях и алгоритмах, но не об интерфейсных и других дизайнерских решениях. Читатели таких работ получат представление о том, что делает реализация; пользователи реализации должны будут знать, какие функции вызывать, что означают аргументы и т. д. Как пользователь, большую часть времени можно жить без первого и просто рассматривать библиотеку как черный ящик, но без него нельзя обойтись. информация об интерфейсе.

Это хороший вопрос. В первом приближении код должен пытаться самодокументироваться. Так, например, если программное обеспечение является командной строкой, вы должны быть в состоянии сделать executable --helpили executable -hдаже executable(если исполняемый файл ничего не делает без аргументов) и получить краткий возврат сообщения об использовании.

Во-вторых, я думаю, что нереально ожидать, что научные разработчики будут тратить много времени на документирование своего программного обеспечения, поэтому я предлагаю сделать его простым. Краткое текстовое руководство с основными методами и опциями и аннотированной работой и проверкойПримеры использования, переходящие от простых к более сложным (примеры использования очень важны и часто ими пренебрегают), значительно лучше, чем ничего и гораздо больше, чем предлагает большинство научных программных продуктов. Я также хотел бы добавить любимую мозоль о примерах использования. Простое означает простое. Это означает, что если вы пытаетесь проиллюстрировать метод, вы не добавляете десять посторонних концепций или методов, чтобы сбить с толку читателя. Сохраняйте это простым и комментируйте, чтобы читатель знал, что должен делать пример. Я бы также предложил как-то связать примеры использования вручную в тестовом наборе, чтобы они продолжали работать после изменения кода. На самом деле я не знаю, как сделать это хорошим способом, поэтому, пожалуйста, не стесняйтесь обучать меня. Если разработчики хотят стать более модными, убедитесь, что они могут использовать хорошие языки разметки и т. Д., Добавьте справочные страницы и т. Д.

В-третьих, авторы должны рассмотреть возможность написания статьи для публикации, если это необходимо. Обычно это учитывает проектные решения и дает более высокий уровень взгляда на программное обеспечение, чем руководство, или можно ожидать от него. Это будет связано с документацией проектных решений, о которых говорил @Matt.

Конечно, самая важная документация из всех - это сам код, который следует комментировать по мере необходимости. Это предполагает, что код является свободным программным обеспечением. Если это не так, то он значительно менее полезен в качестве научного программного обеспечения (вы действительно хотите использовать черный ящик, где вы не видите, как реализованы методы?), И я, например, не стал бы его использовать.

Чтобы ответить на ваш вопрос о том, как документировать данные и результаты, я бы порекомендовал что-то вроде модуля Python doctest . Это позволяет вам писать учебники или тесты так, чтобы их можно было автоматически проверять.

Если вы заинтересованы в грамотном программировании, взгляните на org-babel . Он является частью режима org в Emacs и, таким образом, предоставляет широкий спектр параметров экспорта (LaTeX, PDF, HTML, ODT) для документации. Emacs может отображать изображения внутри буфера и позволяет вам писать математические уравнения в синтаксисе LaTeX, чтобы вам не приходилось ограничивать себя простой текстовой документацией.

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

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

В Python есть инструменты pep8 и pep257, которые сообщат об отсутствующей или искаженной документации. elpy for Emacs также будет жаловаться на отсутствующую документацию. Соглашения Numpy docstring с reStructuredText хороши для подражания. Тест с pep8, pep257 и doctest можно настроить при автоматическом запуске py.test и tox.