Abstract

This paper introduced coding guidelines for use by academics developing code as part of their research in areas of computer science or similar disciplines. We introduce the guidelines and discuss their success and popularity as a tool for MSc students undertaking five month research projects. The guidelines lead to the use of comments combined with dOxygen as an agile approach to model both the software and the research ideas as they develop and change.

I Introduction

This paper presents our Research Documentation Guidelines for use by researchers in university computer science departments. The guidelines aim to capturing the extra ideas and information that would otherwise be lost when a research project comes to a close. Our implementation combines the guidelines with dOxygen, a JavaDoc like documentation tool for Java, C++ and other languages and tests the adoption and results using multiple five month MSc Project over the course of three years.

The documentation guidelines are one tool in a RAISER [1] development process that aims to improve productivity for the current researcher as well as improving the quality of the software and data collected to assist future researchers.

The RAISER development process is an SDLC specific to Software Engineering by Computer Science Researchers [2] to meet the needs of their research environment. The RAISER/RESET approach splits the long-term work into Research (carried out by researchers under a RAISER methodology) and Development (to be carried out by professionals engineers attached to an academic institution under RESET guidelines). The coding guidelines were tested in a way that simulated the availability of a software engineering with experience in RESET, though no RESET work was conducted.

In our work we aim to develop approaches that meet the RAISER guidelines and experimentally test them. The Documentation Guidelines are one of our oldest tools and have been used over a three year period with increasing success. Success for our approach can be measured along two axes, the perceived benefit by researchers and the adoption rate. The null hypothesis states that the default unplanned approach (without the aid of the documentation guidelines or other similar tools) is equally good and the only approach researchers find acceptable i.e. researchers see no benefit in the approach and it is either not adopted at all or found to be a burden with higher cost than value. We aim to disprove this hypothesis.

Our work uses MSc students engaged in research projects at Lancaster University. As very early stage researchers, MSc students were seen as more likely to try new approaches. As students with hard deadlines and project that only last about 5 months they were also seen as being very discriminating when it came to their own cost / benefit analysis of potential tools. Successful adoption of a tool is itself a validation of a tool having greater benefit than cost.

Our case studies also involved surveys, interviews, observation and analysis of students’ final products. The use of Documentation Guidelines, student perception of their usefulness and the changes to practices and product that the caused were monitored throughout the experiment.

We begin this paper with a discussion of the research environment, followed by an introduction to our experimental basis. Next we examine the problems we hope to solve through the use of documentation guidelines and the rational for using the guidelines we’ve experimented with as the solution. The guidelines themselves are then introduced followed by a discussion of their adoption and the both the researcher and engineers view of their success. We end with a discussion of future work including the possibility of a software tool to augment our approach and our conclusions on the guidelines as a response the problems introduced.

II. The Research Environment

The definition of research used by the Organisation for Economic Co-operation and Development (the OECD) is “creative work undertaken on a systematic basis in order to increase the stock of knowledge” [3]. The tension is between allowing researchers the freedom to creatively explore and ensuring there is a systematic approach. Meeting both goals is a challenge, and one that is usually left to the researcher.

Having examined the research environment we agree that care should be taken not to step on academic freedom, yet the development of software, even for researcher purposes, remains a problem that can be helped by sound engineering. Applied properly, Software Engineering can provide the systematic basis that separates real research from hobby coding. As industry looks more to extreme programming and lighter types of engineering, it becomes possible to again consider the ideas of software engineering that grow out of industry – or at least the concepts we teach our students in order to prepare them for industry – and consider how they could be applied to our own research based problems.

Speaking about software engineering in general, Glass [4] suggests improvement will come from greater appreciation for “ad hoc” approaches. In computing, “ad hoc” is defined as “contrived purely for the purpose in hand rather than planned carefully in advance” [5]. The lack of planning is discipline specific and not part of the general usage of the term. The Latin root of ad hoc means “to this”, an approach can be planned (in advance) yet still be a tailored solution. The coding standard we introduce here is part of a wider set of tools aimed at researchers working in a university environment on small (one to two people) projects. We aim to allow personalised software engineering that is still systematic. We believe this combination best meets both the needs of the computer science research environment and the definitions of research commonly used by funding bodies.

Download the full paper.

Full citation: Andre Oboler and Ian Sommerville, Research Documentation Guidelines: Capturing knowledge, improving research, in proceedings of Fourth International Conference on Information Technology : New Generations (ITNG 2007), Las Vegas, Nevada, USA, April 2-4, 2007