¿Cómo revisar un artículo sobre herramientas de software?

Una perspectiva es del Journal of Open Source Software, que establece explícitamente pautas para los revisores que cubren estas preguntas ( http://joss.theoj.org/about#reviewer_guidelines ).

Una cita (ligeramente editada) de las demandas:

Licencia de software Debe haber una licencia aprobada por OSI incluida en el repositorio.[...]

Documentación Debe haber suficiente documentación para que usted, el revisor, comprenda la funcionalidad principal del software que se está revisando.

Una declaración de necesidad Los autores deben indicar claramente qué problemas está diseñado para resolver el software y quién es el público objetivo.

Instrucciones de instalación Debe haber una lista de dependencias claramente establecida. Idealmente, estos deben manejarse con una solución de administración de paquetes automatizada.

• Bueno: un archivo de administración de paquetes como Gemfile o package.json o > equivalente
• OK: Una lista de dependencias para instalar
• Malo (no aceptable): Dependencia de otro software no mencionado por los autores

Ejemplo de uso Los autores deben incluir ejemplos de cómo usar el software (idealmente para resolver problemas de análisis del mundo real).

Documentación de la API Los revisores deben verificar que la API del software esté documentada en un nivel adecuado. Esta decisión se deja en gran medida a discreción del revisor y su experiencia en la evaluación del software. [...]

Se recomienda encarecidamente a los autores de pruebas que incluyan un conjunto de pruebas automatizado que cubra la funcionalidad principal de su software.

• Bueno: un conjunto de pruebas automatizado conectado a un servicio externo como Travis-CI o similar
• OK: pasos manuales documentados que se pueden seguir para verificar la funcionalidad esperada del software (por ejemplo, un archivo de entrada de muestra para afirmar el comportamiento)
• Malo (no aceptable): no hay forma de que usted, el revisor, verifique si el software funciona

Directrices de la comunidad Debe haber directrices claras para terceros que deseen: Contribuir con el software, informar problemas con el software o buscar soporte.

Esta es una forma valiosa de pensar sobre la revisión de software, y creo que deberíamos acercarnos a esto. ¡Pero aún no está aceptado! En mi campo, la mayoría de los artículos sobre "métodos" ni siquiera incluyen software, y los que sí lo hacen casi con seguridad fallarían en estas pruebas. (Nunca había oído hablar de la integración continua hasta hace poco, por ejemplo).

Nunca he revisado un artículo, pero como alguien que produce software (en bioinformática), esto es lo que me gustaría saber de un revisor, ampliando de su lista:

• ¿Es descargable y tiene licencia?

  Modifiqué su primer punto porque el código debería estar disponible para otros y debería tener una licencia para saber qué pueden hacer otros usuarios/desarrolladores con esa herramienta.

• ¿Funciona bien? ¿Los autores hicieron un esfuerzo para escribir la mejor herramienta?

• ¿Podrías instalar la herramienta en tu configuración?

• ¿Son suficientes mis pruebas para comprobar que el software funciona como se esperaba?

• ¿Qué más podría hacer para asegurarme de que funciona bien?

• ¿Es el idioma de la herramienta una buena elección? _{¿Existe una comunidad de usuarios y desarrolladores para ese nicho en ese idioma?}

• ¿Está bajo control de versiones? ¿La herramienta está bajo control de versiones?

Las herramientas suelen desarrollarse cuando hay un problema:

• ¿Mi herramienta resuelve correctamente el problema planteado?
• ¿Se podría usar esta herramienta en otros problemas/situaciones en las que no haya pensado?
• ¿Existen otros métodos para abordar el problema que desconozco?
• ¿Tomé en cuenta todos los factores relevantes o me olvidé de algo?

Las herramientas generalmente se prueban en un conjunto de datos determinado o se comparan con diferentes herramientas, como se indica en un comentario. _{Esto puede ser interesante si también se informan resultados negativos.}

• ¿Elegí un buen conjunto de datos?
• ¿Elegí bien las herramientas con las que comparar mi herramienta?
• ¿Es suficiente la documentación?
• ¿Qué tan fácil es entender cómo funciona la herramienta?
• ¿Explica claramente cuándo debe usar esta herramienta?
• ¿Proporciona suficientes ejemplos o escenarios en los que esta herramienta podría ser útil?
• ¿Son las funciones/métodos/módulos... fácilmente comprensibles?
• ¿Necesito explicar algo mejor?

El software a veces es desarrollado por varias personas y varios años:

• ¿La documentación de la herramienta es consistente? ¿Olvidé hacer que el estilo y la documentación fueran coherentes?
• ¿Tiene un enfoque claro? ¿O me salí por la tangente con otras funciones que no aportan nada a la herramienta y/o al problema?

Cuando use el software, surgirán preguntas, usted como revisor puede verificar cómo se manejará:

• ¿Cuenta con el apoyo de los autores? ¿En una lista de correo, un foro o similar? _{De preferencia abierto para evitar que dos usuarios tengan la misma pregunta}
• ¿Se explica o se piensa en el apoyo a largo plazo?

Como notó, algunas de estas preguntas pueden ser abordadas por la comunidad, pero usted, como revisor, tiene la oportunidad de verificar que el artículo de ese software explica y resuelve un problema para la comunidad, que está razonablemente bien hecho y bien pensado.

Es posible que desee evitar revisar trivialidades y cosas inútiles. Así que, además de lo dicho por Llopis , preguntar si la herramienta resuelve un problema interesante . Sí, esta es una pregunta vaga y amplia, así que siéntete libre de adaptarla a tu área. Por ejemplo, en los métodos formales, las herramientas son el alfa y el omega del progreso, por lo que los creadores de herramientas deben obtener el crédito académico adecuado por el trabajo adecuado , por ejemplo, produciendo mejores resultados en los puntos de referencia estándar que los competidores.

Además, tenga en cuenta que los documentos de herramientas suelen ser diferentes de los documentos de investigación y deben evaluarse de manera diferente, entre ellos. Ciertas conferencias tienen pistas especiales de herramientas puras. En tales casos, debe ser tarea del PC proporcionar la plantilla correspondiente para la evaluación.

Solo he escrito pero no he revisado tal documento todavía. Mi perspectiva personal proviene de los campos de los sistemas complejos y la computación científica, pero ofrezco algunas ideas generalizables.

Estructuro mi respuesta según los criterios típicos aplicados a los trabajos de investigación:

Solvencia

Podría decirse que este es el aspecto más difícil de traducir y más dependiente del campo. Por ejemplo, en un campo de simulación o experimental, no es factible verificar completamente los resultados de un trabajo de investigación, ya que esto significaría rehacerlo completamente desde cero; todo lo que puede hacer (y se le pide que haga como revisor) es verificar si los métodos empleados son apropiados y los resultados son consistentes. Por otro lado, en algunos campos teóricos, puede (y se espera que lo haga) verificar cada cálculo y demostración.

Sugiero aplicar el mismo estándar a los artículos de software que a los artículos de investigación y, en particular, a los artículos de métodos en el campo respectivo. Después de todo, si se acepta un artículo de software, debería poder citarse como "evidencia" como un artículo de investigación regular y, en particular, un artículo de métodos: en otras palabras, citar el artículo de software debería ser suficiente como evidencia de que la tarea respectiva se realizó correctamente¹ .

Entonces, como criterio práctico:

1. Considere un documento típico que citaría este documento de software. Suponga que el artículo lo satisface con respecto a la solidez científica de lo contrario.
2. Suponga que la cita se reemplazaría con el contenido del documento de software.
3. ¿Aún consideraría el artículo científicamente sólido (de acuerdo con los estándares de su campo)?

Criterios más específicos incluirían:

• ¿Se eligen adecuadamente los algoritmos, bibliotecas, etc. empleados, es decir, se pueden mantener con el mismo estándar, se ajustan a la aplicación y son de última generación?

• ¿El documento respalda suficientemente las afirmaciones realizadas sobre la corrección, la eficiencia y la facilidad de uso del software? Este punto puede diferir ligeramente dependiendo del formato de publicación. Por ejemplo, si el software en sí se considera parte de la publicación: ¿Puede verificar estas afirmaciones (posiblemente utilizando pruebas, puntos de referencia, documentación y ejemplos proporcionados)?

• ¿El software se adhiere lo suficiente a las buenas prácticas de ingeniería de software, como las pruebas, que garantizan que funciona según lo previsto?

^{¹ Salvo el manejo correcto del software, que por supuesto debe ser descrito adecuadamente por el documento de cita}

Novedad

Si el lugar de publicación tiene un umbral de novedad, intente traducirlo a software. Pragmáticamente, se pregunta si el artículo en cuestión contribuirá positivamente al factor de impacto de la revista (o alguna otra métrica). Algunos criterios específicos que vienen a la mente:

• ¿Puede el nuevo software realizar tareas que no hayan sido automatizadas antes?
• ¿Es el software más eficiente, más preciso o más fácil de usar que los softwares existentes por un factor relevante?
• ¿Es el software un módulo para un lenguaje de programación que antes no tenía tal módulo y que es relevante para los científicos en el área respectiva²?
• ¿Con qué probabilidad consideraría que un usuario de un software existente que realiza las mismas tareas cambiará al software presentado en el documento?
• ¿Es sostenible el software, es decir, espera que los autores u otra persona mantenga el código en los años venideros? ¿Se puede mantener y ampliar el código base o era un código heredado en el momento en que se escribió? ¿El software depende de algunas bibliotecas exóticas que pueden fallar en un futuro cercano³?

^{² ¿Quién necesitaría una biblioteca CAS para Malboge ?
³ Este es un problema real: una de mis motivaciones para escribir un software para una tarea específica fue que los softwares existentes dependían de bibliotecas descontinuadas y obsoletas o de una biblioteca que se modificó mucho de una manera no compatible con versiones anteriores (que a su vez era posible porque casi nadie lo usaba).}

Otros criterios

La mayoría de los demás criterios deberían ser fáciles de traducir, en particular cuando piensa en un documento de método:

• ¿Está bien escrito el artículo, utiliza una estructura razonable, terminología coherente, etc.?
• ¿Está claro para qué tareas se puede y no se puede aplicar el software?
• ¿Se analizan adecuadamente las deficiencias del software (eficiencia, escalabilidad, problemas con tareas específicas)?
• ¿Se analizan adecuadamente las posibles expansiones y mejoras futuras?

La respuesta real depende principalmente de la revista/conferencia/taller específico. Mi propia experiencia es de Computación de alto rendimiento: puede haber algunas prácticas comunes dependientes del campo, pero creo que la mayoría será similar.

Lo principal que veo diferente es que no está revisando la herramienta , está revisando el documento . Tampoco es lo mismo un paper sobre una herramienta que una documentación . Concentre su revisión más en la contribución científica del artículo que en la herramienta en sí. Idealmente, el papel en sí debería ser útil sin la herramienta. Incluso diría que un documento que describe un intento fallido de desarrollar una nueva herramienta puede ser una contribución valiosa para una audiencia un poco restringida.

No existe una limitación general para las herramientas de código abierto (a menos, por supuesto, que su lugar sea el Journal of Open Source Software). Al menos para HPC, los documentos sobre herramientas propietarias no son infrecuentes. Sin embargo, las herramientas disponibles públicamente mejoran la reproducibilidad de un artículo.

Al mismo tiempo, cualquier artículo científico debe incluir una discusión adecuada del trabajo relacionado . El documento debe describir las herramientas que usan técnicas similares o abordan objetivos similares y cómo la nueva herramienta es diferente. Si la herramienta aprovecha una técnica publicada, se debe hacer referencia a ella. El trabajo relacionado también puede incluir referencias que subrayan los casos de uso.

Un documento de herramientas no necesita producir una descripción detallada sobre cómo usar la herramienta, pero debe centrarse en los conceptos novedosos aplicados en la herramienta, ya sea en términos de aspectos de implementación o características. Los casos de uso también son una parte importante, pero más con un enfoque para evaluar la herramienta (por ejemplo, comparaciones de rendimiento) y cómo es útil en lugar de instruir al usuario sobre cómo usarla.

Si bien algunos talleres tienen un enfoque claro en las herramientas, no hay solo documentos de herramientas puras. Es posible presentar una herramienta para el análisis/optimización de X en un taller sobre X. O si una herramienta hace un uso intensivo de una técnica de Y, sería adecuada para una conferencia de Y. Este cambio en la audiencia debe reflejarse en el enfoque del artículo.