Inline Documentation Research Articles

Approaching Software Engineering for Marine Sciences: A Single Development Process for Multiple End-User Applications

Research software is currently used by a large number of scientists on a daily basis, and everything indicates that this trend will continue to increase in the future. Most of this scientific software is very often developed by the researchers themselves, who usually make it available to the rest of the scientific community. Although the relationship between science and software is unquestionably useful, it is not always successful. Some of the critical problems that scientists face include a lack of training in software development, a shortage of time and resources, or difficulty in effectively cooperating with other colleagues. Additional challenges arise in the context of increasingly common cross-cutting and multidisciplinary research. This often results in the developed software and code being slow, not reusable, lacks visibility and dissemination, and in the worst cases it is defective and unreliable. Therefore, a multidisciplinary framework is needed to meet the demands of both scientists and software engineers and handle the situation successfully. However, a multidisciplinary team is not always sufficient to solve this problem, and it is necessary to have links between scientists and developers: software engineers with a solid scientific background. This paper presents the approach used in the framework of the PROTOCOL project, and more particularly in the development of its applied software, in which a tool for the characterization of climate agents has been developed. The main guidelines of the development process include, among others, modularity, distributed control version, unit testing, profiling, inline documentation and the use of best practices and tools.

Assessing the quality factors found in in-line documentation written in natural language: The JavadocMiner

An important software engineering artifact used by developers and maintainers to assist in software comprehension and maintenance is source code documentation. It provides the insight needed by software engineers when performing a task, and therefore ensuring the quality of this documentation is extremely important. In-line documentation is at the forefront of explaining a programmer's original intentions for a given implementation. Since this documentation is written in natural language, ensuring its quality so far needed to be performed manually. In this paper, we present an effective and automated approach for assessing the quality of in-line documentation using a set of heuristics, targeting both the quality of language and consistency between the source code and its comments. Our evaluation is made up of two parts: We first apply the JavadocMiner tool to the different modules of two open source applications (ArgoUML and Eclipse) in order to automatically assess their intrinsic comment quality. In the second part of our evaluation, we correlate the results returned by the analysis with bug defects reported for the individual modules in order to examine connections between natural language documentation and source code quality.

Sustainable, Extensible Documentation Generation Usinginlinedocs

This article presents inlinedocs, an R package for generating documentation from comments. The concept of structured, interwoven code and documentation has existed for many years, but existing systems that implement this for the R programming language do not tightly integrate with R code, leading to several drawbacks. This article attempts to address these issues and presents 2 contributions for documentation generation for the R community. First, we propose a new syntax for inline documentation of R code within comments adjacent to the relevant code, which allows for highly readable and maintainable code and documentation. Second, we propose an extensible system for parsing these comments, which allows the syntax to be easily augmented.

Encoding Transparency: Literate Programming and Test Generation for Scientific Function Libraries

We present a variation on literate programming (see Knuth: 1984, 1992) targeting multiple simultaneous readerships, both human (e.g., coders, testers, analysts, etc.) and compilers/interpreters (e.g., C , Python, Fortran, etc.). The technique exploits existing commenting syntax available in all common programming languages to provide inline documentation and other semantic markup, which can then be used in test generation and code translation. To keep the problem manageable, we restrict attention to scientific function libraries (i.e., libraries of numerical routines adhering to the functional programming rule of “no side effects”). We offer a prototype implementation in XSLT and DocBook.

Process analysis of fluidized bed granulation

This study assesses the fluidized bed granulation process for the optimization of a model formulation using in-line near-infrared (NIR) spectroscopy for moisture determination. The granulation process was analyzed using an automated granulator and optimization of the verapamil hydrochloride formulation was performed using a mixture design. The NIR setup with a fixed wavelength detector was applied for moisture measurement. Information from other process measurements, temperature difference between process inlet air and granules (T(diff)), and water content of process air (AH), was also analyzed. The application of in-line NIR provided information related to the amount of water throughout the whole granulation process. This information combined with trend charts of T(diff) and AH enabled the analysis of the different process phases. By this means, we can obtain in-line documentation from all the steps of the processing. The choice of the excipient affected the nature of the solid-water interactions; this resulted in varying process times. NIR moisture measurement combined with temperature and humidity measurements provides a tool for the control of water during fluid bed granulation.

Computers in Medicine-Reply

In Reply.— It is a pleasure to respond to the comments of Dr Yasnoff and his associates. Although my review was limited to computers in the clinical laboratory, clearly the use of computers in medicine includes a wide range of topics, involving all medical specialities. With regard to in-line documentation, my experience is quite different from that of Dr Yasnoff and his associates. By in-line documentation, I mean a complete description of program flow and program logic, incorporated within the program itself. Such in-line documentation is not nearly as old as programming. In our experience, the in-line approach solves many documentation problems. Documentation as part of the computer program is on hand and easily updated when programs are revised. Because in-line documentation is updated when programs are revised, it accurately reflects real life code. This improved accuracy greatly facilitates program maintenance. Our favorable experience is consistent with experience at other