Как просмотреть статью о программном инструменте?

Одна из точек зрения взята из Журнала программного обеспечения с открытым исходным кодом, в котором четко изложены правила для рецензентов, касающиеся этих вопросов ( http://joss.theoj.org/about#reviewer_guidelines ).

(Слегка отредактированная) цитата требований:

Лицензия на программное обеспечение В репозиторий должна быть включена одобренная OSI лицензия.[...]

Документация У вас, рецензента, должно быть достаточно документации, чтобы понять основные функциональные возможности рецензируемого программного обеспечения.

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

Инструкции по установке Должен быть четко указан список зависимостей. В идеале они должны обрабатываться с помощью автоматизированного решения для управления пакетами.

• Хорошо: файл управления пакетами, такой как Gemfile или package.json или > эквивалентный
• OK: список зависимостей для установки
• Плохо (неприемлемо): зависимость от другого программного обеспечения, не указанного авторами.

Примеры использования Авторы должны включать примеры использования программного обеспечения (в идеале для решения реальных задач анализа).

Документация API Рецензенты должны убедиться, что программный API задокументирован на надлежащем уровне. Это решение в значительной степени остается на усмотрение рецензента и его опыта оценки программного обеспечения. [...]

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

• Хорошо: набор автоматизированных тестов, подключенный к внешней службе, такой как Travis-CI или аналогичный.
• OK: задокументированные ручные шаги, которые можно выполнить для проверки ожидаемой функциональности программного обеспечения (например, образец входного файла для проверки поведения)
• Плохо (неприемлемо): у вас, рецензента, нет возможности проверить, работает ли программное обеспечение.

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

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

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

• Можно ли его скачать и есть ли лицензия?

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

• Это работает хорошо? Приложили ли авторы усилия, чтобы написать лучший инструмент?

• Не могли бы вы установить инструмент в своих настройках?

• Достаточно ли моих тестов, чтобы убедиться, что программное обеспечение работает должным образом?

• Что еще я могу сделать, чтобы убедиться, что он работает хорошо?

• Является ли язык инструмента хорошим выбором? _{Есть ли сообщество пользователей и разработчиков для этой ниши на этом языке?}

• Он находится под контролем версий? Инструмент находится в стадии версии?

Инструменты обычно разрабатываются, когда есть проблема:

• Правильно ли мой инструмент решает поставленную задачу?
• Можно ли использовать этот инструмент в других проблемах/ситуациях, о которых я не подумал?
• Существуют ли другие методы решения проблемы, о которой я не знаю?
• Я учел все соответствующие факторы или что-то забыл?

Инструменты обычно тестируются в заданном наборе данных или сравниваются с другими инструментами, как указано в комментарии. _{Это может быть интересно, если сообщаются и отрицательные результаты.}

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

Программное обеспечение иногда разрабатывается несколькими людьми и несколько лет:

• Согласована ли документация по инструменту? Не забыл ли я согласовать стиль и документацию?
• Есть ли у него четкая направленность? Или я пошел по касательной с другими функциями, которые ничего не привносят в инструмент и/или проблему?

При использовании программного обеспечения возникнут вопросы, вы, как рецензент, можете проверить, как они будут решаться:

• Есть ли поддержка со стороны авторов? В списке рассылки, на форуме и т.п.? _{Желательно открытым, чтобы два пользователя не задавали один и тот же вопрос.}
• Долгосрочная поддержка объяснена или задумана?

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

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

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

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

Я структурирую свой ответ по типичным критериям, применяемым к исследовательским работам:

надежность

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

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

Итак, практический критерий:

1. Рассмотрим типичную статью, в которой будет цитироваться этот документ по программному обеспечению. Предположим, что в остальном статья удовлетворяет вас с точки зрения научной обоснованности.
2. Предположим, что цитата будет заменена содержанием документа по программному обеспечению.
3. Считаете ли вы статью научно обоснованной (согласно стандартам вашей области)?

Более конкретные критерии включают:

• Правильно ли выбраны используемые алгоритмы, библиотеки и т. д., т. е. могут ли они соответствовать одному и тому же стандарту, подходят ли они для приложения и соответствуют ли они уровню техники?

• Достаточно ли документ подтверждает заявления о правильности, эффективности и удобстве использования программного обеспечения? Этот пункт может немного отличаться в зависимости от формата публикации. Например, если само программное обеспечение рассматривается как часть публикации: можете ли вы проверить эти утверждения (возможно, используя предоставленные тесты, эталонные тесты, документацию и примеры)?

• В достаточной ли степени программное обеспечение соответствует передовым методам разработки программного обеспечения, таким как тесты, которые гарантируют, что оно работает должным образом?

^{¹ за исключением правильного обращения с программным обеспечением, которое, конечно же, должно быть надлежащим образом описано в цитирующем документе}

Новинка

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

• Может ли новое программное обеспечение выполнять какие-либо задачи, которые раньше не были автоматизированы?
• Является ли программное обеспечение более эффективным, точным или простым в использовании, чем существующее программное обеспечение, по соответствующему фактору?
• Является ли программное обеспечение модулем для языка программирования, у которого раньше не было такого модуля и который актуален для ученых в соответствующей области²?
• Насколько вероятно, по вашему мнению, что пользователь существующего программного обеспечения, выполняющий те же задачи, переключится на программное обеспечение, представленное в статье?
• Является ли программное обеспечение устойчивым, то есть: вы ожидаете, что авторы или кто-то еще будет поддерживать код в ближайшие годы? Является ли кодовая база поддерживаемой и расширяемой, или это был устаревший код на момент написания? Зависит ли программное обеспечение от каких-то экзотических библиотек, которые могут выйти из строя в ближайшем будущем³?

^{² Кому может понадобиться библиотека CAS для Malboge ?
³ Это актуальная проблема: одним из моих мотивов для написания программного обеспечения для конкретной задачи было то, что существующие программы зависели либо от снятых с производства и устаревших библиотек, либо от библиотеки, которая была сильно изменена и несовместима с предыдущими версиями (что, в свою очередь, было возможно, потому что им почти никто не пользовался).}

Другие критерии

Большинство других критериев должно быть легко перевести, особенно когда вы думаете о методической статье:

• Написана ли статья хорошо, с использованием разумной структуры, последовательной терминологии и т. д.?
• Понятно ли, для каких задач можно и нельзя применять ПО?
• Обсуждаются ли должным образом недостатки программного обеспечения (эффективность, масштабируемость, проблемы с конкретными задачами)?
• Обсуждаются ли должным образом возможные будущие расширения и улучшения?

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

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

Нет никаких общих ограничений для инструментов с открытым исходным кодом (если, конечно, вы не используете Журнал программного обеспечения с открытым исходным кодом). По крайней мере, для HPC статьи о проприетарных инструментах не редкость. Однако общедоступные инструменты улучшают воспроизводимость бумаги.

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

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

В то время как некоторые мастерские имеют четкую направленность на инструменты, существует не только чистая бумага для инструментов. Инструмент для X-анализа/оптимизации можно представить на семинаре по X. Или, если инструмент активно использует методику из Y, он подойдет для Y-конференции. Этот сдвиг в аудитории должен отражаться в фокусе документа.