By Heather Packer, Agent and research fellow at the University of Southampton.

Extending existing code bases can be problematic and time confusing due to a lack of documentation and comments, and a lack of clarity of the workflow between components. I have spent the last couple of months extending RoboCup Rescue - the standard, multi-agent search and rescue simulation platform - so that it contains more detailed and realistic information that can be modelled with ontologies. My extension enables agents to learn new information from these ontologies, and make choices based on the information they learn.

The issues I encountered while extending RoboCup Rescue are common in any software produced for research, and this was highlighted at the recent Collaborations Workshop 2012 in Oxford. Most relevant to my work were the discussions on Writing code for everybody and Best practices for documenting scientific software development.

In the Writing Code for Everybody discussion, the group highlighted the fact that researchers who develop software have different requirements to those who develop for industry or as a hobby. Researchers write code to test theorems and algorithms, but their time and resource constraints prevent them from developing with a focus on the later re-use of the software by others. However, there is now a strong focus on making research repeatable, and this should lead researchers to develop software for others to reuse. The group made some suggestions to help the re-use movement, such as educating researcher-developers and rewarding good software development.

These findings mirror my own experiences with RoboCup Rescue: it has been written to be extensible, but its specific design patterns have added complexity. Specifically, every component in the system is implemented via an abstract class, and via an interface. In addition, each component is also spawned via a factory class, or via a singleton container class. While this pattern has enabled the system to be generic and extensible, it makes it difficult to track references through the system, because all references are to abstract classes and not those that are actually instantiated. However, some documentation has been produced that explains how to extend the software, which I discuss below.

In the best practices for documenting scientific software development discussion the group postulated that there are different types of audiences for documentation. For example, users require installation guides, whereas developers require information on how to integrate code. Published papers provide information for researchers, like performance benchmarks and descriptions of algorithms. We concluded that best practices include a two-page, ten-minute, quickstart guide, and dynamic mechanisms to support users such as mailing lists. The bottom line of the discussion is that bad documentation adversely affects the uptake of software, whereas good documentation encourages people to contribute and use it.

The RoboCup Rescue platform is documented online, specifically a documentation wiki, which outlines the method to create new modules for the platform. However, this documentation is patchy, and has gaps, which mean that the tutorials can be hard to follow to completion.

Some links about writing code for everybody:

• Software carpentry
• HECToR training courses
• Book: HPC for scientists and engineers
• Nano publications
• Sustainable software for Audio and Music Research

Some links about best practices for documenting scientific software development:

• Free software to record interactions e.g. Camtasia, Camstudio.
• Blogs: Why RTFM doesn't work, Why users don't read documentation.

The Collaborations Workshop left me with a feeling that, although issues exist in software development in the higher education sector, they are well known and we are already improving our practices. A key conclusion is that your software may be beneficial to others in future, and that a small effort to document it will help yourself and, more importantly, others in the future.