Source Code Documentation Research Articles

A Review on Source Code Documentation

Context: Coding is an incremental activity where a developer may need to understand a code before making suitable changes in the code. Code documentation is considered one of the best practices in software development but requires significant efforts from developers. Recent advances in natural language processing and machine learning have provided enough motivation to devise automated approaches for source code documentation at multiple levels. Objective: The review aims to study current code documentation practices and analyze the existing literature to provide a perspective on their preparedness to address the stated problem and the challenges that lie ahead. Methodology: We provide a detailed account of the literature in the area of automated source code documentation at different levels and critically analyze the effectiveness of the proposed approaches. This also allows us to infer gaps and challenges to address the problem at different levels. Findings: (1) The research community focused on method-level summarization. (2) Deep learning has dominated the past five years of this research field. (3) Researchers are regularly proposing bigger corpora for source code documentation. (4) Java and Python are the widely used programming languages as corpus. (5) Bilingual Evaluation Understudy is the most favored evaluation metric for the research persons.

Machine Learning Approaches Identify Genes Containing Spatial Information From Single-Cell Transcriptomics Data.

The development of single-cell sequencing technologies has allowed researchers to gain important new knowledge about the expression profile of genes in thousands of individual cells of a model organism or tissue. A common disadvantage of this technology is the loss of the three-dimensional (3-D) structure of the cells. Consequently, the Dialogue on Reverse Engineering Assessment and Methods (DREAM) organized the Single-Cell Transcriptomics Challenge, in which we participated, with the aim to address the following two problems: (a) to identify the top 60, 40, and 20 genes of the Drosophila melanogaster embryo that contain the most spatial information and (b) to reconstruct the 3-D arrangement of the embryo using information from those genes. We developed two independent techniques, leveraging machine learning models from least absolute shrinkage and selection operator (Lasso) and deep neural networks (NNs), which are applied to high-dimensional single-cell sequencing data in order to accurately identify genes that contain spatial information. Our first technique, Lasso.TopX, utilizes the Lasso and ranking statistics and allows a user to define a specific number of features they are interested in. The NN approach utilizes weak supervision for linear regression to accommodate for uncertain or probabilistic training labels. We show, individually for both techniques, that we are able to identify important, stable, and a user-defined number of genes containing the most spatial information. The results from both techniques achieve high performance when reconstructing spatial information in D. melanogaster and also generalize to zebrafish (Danio rerio). Furthermore, we identified novel D. melanogaster genes that carry important positional information and were not previously suspected. We also show how the indirect use of the full datasets’ information can lead to data leakage and generate bias in overestimating the model’s performance. Lastly, we discuss the applicability of our approaches to other feature selection problems outside the realm of single-cell sequencing and the importance of being able to handle probabilistic training labels. Our source code and detailed documentation are available at https://github.com/TJU-CMC-Org/SingleCell-DREAM/.

Development of the Community Water Model (CWatM v1.04) – a high-resolution hydrological model for global and regional assessment of integrated water resources management

Abstract. We develop a new large-scale hydrological and water resources model, the Community Water Model (CWatM), which can simulate hydrology both globally and regionally at different resolutions from 30 arcmin to 30 arcsec at daily time steps. CWatM is open source in the Python programming environment and has a modular structure. It uses global, freely available data in the netCDF4 file format for reading, storage, and production of data in a compact way. CWatM includes general surface and groundwater hydrological processes but also takes into account human activities, such as water use and reservoir regulation, by calculating water demands, water use, and return flows. Reservoirs and lakes are included in the model scheme. CWatM is used in the framework of the Inter-Sectoral Impact Model Intercomparison Project (ISIMIP), which compares global model outputs. The flexible model structure allows for dynamic interaction with hydro-economic and water quality models for the assessment and evaluation of water management options. Furthermore, the novelty of CWatM is its combination of state-of-the-art hydrological modeling, modular programming, an online user manual and automatic source code documentation, global and regional assessments at different spatial resolutions, and a potential community to add to, change, and expand the open-source project. CWatM also strives to build a community learning environment which is able to freely use an open-source hydrological model and flexible coupling possibilities to other sectoral models, such as energy and agriculture.

Wannier90 as a community code: new features and applications

Wannier90 is an open-source computer program for calculating maximally-localised Wannier functions (MLWFs) from a set of Bloch states. It is interfaced to many widely used electronic-structure codes thanks to its independence from the basis sets representing these Bloch states. In the past few years the development of Wannier90 has transitioned to a community-driven model; this has resulted in a number of new developments that have been recently released in Wannier90 v3.0. In this article we describe these new functionalities, that include the implementation of new features for wannierisation and disentanglement (symmetry-adapted Wannier functions, selectively-localised Wannier functions, selected columns of the density matrix) and the ability to calculate new properties (shift currents and Berry-curvature dipole, and a new interface to many-body perturbation theory); performance improvements, including parallelisation of the core code; enhancements in functionality (support for spinor-valued Wannier functions, more accurate methods to interpolate quantities in the Brillouin zone); improved usability (improved plotting routines, integration with high-throughput automation frameworks), as well as the implementation of modern software engineering practices (unit testing, continuous integration, and automatic source-code documentation). These new features, capabilities, and code development model aim to further sustain and expand the community uptake and range of applicability, that nowadays spans complex and accurate dielectric, electronic, magnetic, optical, topological and transport properties of materials.

Automatic Source Code Documentation using Code Summarization Technique of NLP

Abstract Source code documentation is an important process for software project maintenance and management. The documentation process always consumes a lot of time and effort from human experts. The software project document should be concise and clear without any ambiguity. Existing source code documentation tools like JavaDoc are very limited in the market. Also, tools can identify only the predefined methods of corresponding programming languages. In this paper, a novel system is proposed to automate the source code documentation process for C programming language using the source code summarization technique of NLP. The core component of this proposed system i.e., Software Word Usage Model (SWUM) build using Context-Free Grammars and NLP preprocessing techniques. This system can successfully generate the documentation for a C program along with predefined and user-defined methods using Natural Language Generation technique. This proposed system can document a program in two major formats; method-based, abstract level and statement-based, detailed level. The proposed system efficiency is evaluated by comparing system-generated source code documentation with an expert generated documentation. Results obtained from that comparison shows that the proposed system can give better performance for small and medium-size software projects.

Mining traces between source code and textual documents

Currently, researchers in computer science are dealing with a major challenge to link the source codes with the software documents. Writing informal documents by using natural and unstructured language causes this problem. In this paper, we present a model for recovery of traceable links between the source code and requirement documents. The proposed method in this paper is executed in four interconnected sections. The first section goes through extracting the features from the documents, which is followed by extracting the features from the source code. During the third section, abbreviations will be completed, using similarity measure as a feature. Finally, data mining algorithms will be implemented to find the hidden links between source code and software documentation. The most outstanding advantage of using this method is to be independent from the language. Also the preliminary results show that the proposed method has a good performance.

Source Code Documentation Generation Using Program Execution

Automated source code documentation approaches often describe methods in abstract terms, using the words contained in the static source code or code excerpts from repositories. In this paper, we describe DynamiDoc: a simple automated documentation generator based on dynamic analysis. Our representation-based approach traces the program being executed and records string representations of concrete argument values, a return value and a target object state before and after each method execution. Then, for each method, it generates documentation sentences with examples, such as “When called on [3, 1.2] with element = 3, the object changed to [1.2]”. Advantages and shortcomings of the approach are listed. We also found out that the generated sentences are substantially shorter than the methods they describe. According to our small-scale study, the majority of objects in the generated documentation have their string representations overridden, which further confirms the potential usefulness of our approach. Finally, we propose an alternative, variable-based approach that describes the values of individual member variables, rather than the state of an object as a whole.

Riboviz: analysis and visualization of ribosome profiling datasets

BackgroundUsing high-throughput sequencing to monitor translation in vivo, ribosome profiling can provide critical insights into the dynamics and regulation of protein synthesis in a cell. Since its introduction in 2009, this technique has played a key role in driving biological discovery, and yet it requires a rigorous computational toolkit for widespread adoption.DescriptionWe have developed a database and a browser-based visualization tool, riboviz, that enables exploration and analysis of riboseq datasets. In implementation, riboviz consists of a comprehensive and flexible computational pipeline that allows the user to analyze private, unpublished datasets, along with a web application for comparison with published yeast datasets. Source code and detailed documentation are freely available from https://github.com/shahpr/RiboViz. The web-application is live at www.riboviz.org.Conclusionsriboviz provides a comprehensive database and analysis and visualization tool to enable comparative analyses of ribosome-profiling datasets. This toolkit will enable both the community of systems biologists who study genome-wide ribosome profiling data and also research groups focused on individual genes to identify patterns of transcriptional and translational regulation across different organisms and conditions.

The Image Curvature Microscope: Accurate Curvature Computation at Subpixel Resolution

We detail in this paper the numerical implementation of the so-called image curvature microscope , an algorithm that computes accurate image curvatures at subpixel resolution, and yields a curvature map conforming with our visual perception. In contrast to standard methods, which would compute the curvature by a finite difference scheme, the curvatures are evaluated directly on the level lines of the bilinearly interpolated image, after their independent smoothing, a step necessary to remove pixelization artifacts. The smoothing step consists in the affine erosion of the level lines through a geometric scheme, and can be applied in parallel to all level lines. The online algorithm allows the user to visualize the image of curvatures at different resolutions, as well as the set of level lines before and after smoothing. Source Code The ANSI C++ implementation reviewed by IPOL is given in the file curv.cpp. The complete source code, code documentation, and online demo are accessible at the IPOL web page of this article 1. The level lines extraction (files levelLine.cpp, lltree.cpp) and level lines smoothing (file gass.cpp) are independent algorithms, out of the scope of this article, and details for their implementation are planned for separate IPOL publications.

An empirical study of the textual similarity between source code and source code summaries

Source code documentation often contains summaries of source code written by authors. Recently, automatic source code summarization tools have emerged that generate summaries without requiring author intervention. These summaries are designed for readers to be able to understand the high-level concepts of the source code. Unfortunately, there is no agreed upon understanding of what makes up a "good summary." This paper presents an empirical study examining summaries of source code written by authors, readers, and automatic source code summarization tools. This empirical study examines the textual similarity between source code and summaries of source code using Short Text Semantic Similarity metrics. We found that readers use source code in their summaries more than authors do. Additionally, this study finds that accuracy of a human written summary can be estimated by the textual similarity of that summary to the source code.

Verifiable source code documentation in controlled natural language

Writing documentation about software internals is rarely considered a rewarding activity. It is highly time-consuming and the resulting documentation is fragile when the software is continuously evolving in a multi-developer setting. Unfortunately, traditional programming environments poorly support the writing and maintenance of documentation. Consequences are severe as the lack of documentation on software structure negatively impacts the overall quality of the software product. We show that using a controlled natural language with a reasoner and a query engine is a viable technique for verifying the consistency and accuracy of documentation and source code. Using ACE, a state-of-the-art controlled natural language, we present positive results on the comprehensibility and the general feasibility of creating and verifying documentation. As a case study, we used automatic documentation verification to identify and fix severe flaws in the architecture of a non-trivial piece of software. Moreover, a user experiment shows that our language is faster and easier to learn and understand than other formal languages for software documentation.

Reading between the lines: Source code documentation as a conservation strategy for software-based art

Conservation expertise required for software-based art varies depending on the nature and function of its components. Our focus in this study is technology, specifically related to the impact of changes and upgrades to the operating environment that can adversely impact future exhibition of software-based art. In our research to date, we found that each specific work requires individual analysis and conservation strategies due to unique technical risks. We also concluded that artist-generated source code is a primary risk for software-based works. We then devoted the next phase of our research to a closer examination of risks associated with source code. The purpose of the research reported in this article is to investigate whether examining and documenting the source code can inform conservation practice. A corollary second goal is to define relevant best practices for documenting source code for software-based art. In order to address these questions, we selected two artworks at the Museum of Modern Art for a collaborative study using students and faculty from both the Museum Studies and Computer Science departments at New York University. This collaboration helped ensure that technology skills complemented a deep understanding of art history in the museum context. We based the methodology for our study on current software engineering practices and composed diagrams and narrative documents to reflect what we found in the source code. We also relied on artist interviews to explore the requirements and goals of the system, and user manuals to assist in understanding the implementation and physical installation of the works. It was our hypothesis that once the behavior of software-based art is understood by combining a standard software engineering approach with considerations specific to artist and museum needs, conservators and programmers will be better prepared to address changes in the operating environment. Based on our experience, we found this to be true. We conclude this paper with plans for our next phase of research.

Djeen (Database for Joomla!’s Extensible Engine): a research information management system for flexible multi-technology project administration

BackgroundWith the advance of post-genomic technologies, the need for tools to manage large scale data in biology becomes more pressing. This involves annotating and storing data securely, as well as granting permissions flexibly with several technologies (all array types, flow cytometry, proteomics) for collaborative work and data sharing. This task is not easily achieved with most systems available today.FindingsWe developed Djeen (Database for Joomla!’s Extensible Engine), a new Research Information Management System (RIMS) for collaborative projects. Djeen is a user-friendly application, designed to streamline data storage and annotation collaboratively. Its database model, kept simple, is compliant with most technologies and allows storing and managing of heterogeneous data with the same system. Advanced permissions are managed through different roles. Templates allow Minimum Information (MI) compliance.ConclusionDjeen allows managing project associated with heterogeneous data types while enforcing annotation integrity and minimum information. Projects are managed within a hierarchy and user permissions are finely-grained for each project, user and group.Djeen Component source code (version 1.5.1) and installation documentation are available under CeCILL license from http://sourceforge.net/projects/djeen/files and supplementary material.

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.

Establishing community models as the underpinning of neuroscience: linking computational and experimental data

In Physics, as in other “hard sciences”, both research and education are built around systems and their associated models that are accepted as fundamental to the field. This is not the case within Neuroscience, although the existence of simulation systems like GENESIS and NEURON are producing an informal propagation of particular models between laboratories. One of the core tenants of the reconfiguration of GENESIS is that fully developed community models will not exist until the process of building, evaluating, and propagating models is incorporated into the structure of the simulation system itself. To be successful, such systems will also have to provide explicit links to experimental data and procedures. GENESIS 3.0 (G-3) conforms to the CBI federated software architecture [1]. It is explicitly constructed around an ideal user workflow [2] that provides an organizing principle for simulator use. The modular nature of the system separates low-level numeric data from high-level biological representations, as well as the data and control functions. This facilitates the interface of different databases to significantly enhance two broad categories of user and developer experience. One is organized around an ideal user workflow while the other supports a multi-level documentation system that informs user and developer concerns. We show how this information infrastructure supports scientific communication through the development of community models that can then integrate computational models and experimental neuroscience. G-3 documentation is organized into seven levels, each served by a single repository: (1-2) Introductory material and user guides, (3-4) Automated use cases and technical guides, (5-7) Algorithm, API and hyperlinked source code documentation. Both within each repository and across the different levels, documents are organized by a user defined tagging system that creates horizontal and vertical reader flows. This simplifies the communication of computational models by separating the technical aspects of a model from its scientific content and interpretation. The dynamic creation of horizontal and vertical reader flows allows to reinterpret the capabilities of this documentation system from the perspective of a model publication workflow. The lowest levels (Levels 5-7) describe purely technical components of model implementation entirely devoid of scientific interpretation. Higher levels communicate the nontechnical scientific narratives generated by both computational and experimental projects. For example, Level 4-3: Explain biological mechanisms obtained by computational studies, community models, and experimental research, Level 2: Integrates results of computational and experimental neuroscience, and Level 1: General introductions and reviews of neuroscience. This results in a communication gradient where increasing detail about any aspect of a publication is accessible from a given level. We show examples of (1) Horizontal workflows, e.g. model lineage, and (2) Vertical workflows, e.g. “drilling down” from the biological concepts of a model to increasingly technical details of model implementation or, vice-versa, starting from technical implementations going up to their uses in models and simulations and their scientific interpretation. These are the first steps in the implementation of a model-based publication system for scientific communication [3]. Here, we present a new view of the G-3 documentation system as a model sharing system that not only incorporates the models and their interpretation, but also their technical and algorithmic implementation and their relationship with the experimental data on which they are based. Employed in this way, the documentation system also enhances G-3 to support the integration and communication of computational and experimental neuroscience. This research was supported by NSF grant HRD-0932339 to the University of Texas at San Antonio. Hugo Cornelis is supported by the CREA Financing program (CREA/07/027) of the K.U.Leuven, Belgium. Hugo Cornelis, Armando L. Rodriguez and Allan D. Coop are supported by NIH grant 3 R01 NS049288-06S1 to James M. Bower.

Opening the black box—Development, testing and documentation of a mechanistically rich agent-based model

Although increasingly widely used in biology, complex adaptive simulation models such as agent-based models have been criticised for being difficult to communicate and test. This study demonstrates the application of pattern-oriented model testing, and a novel documentation procedure to present a detailed agent-based model of the European brown hare, a species in widespread decline in Europe. The model was built based on available literature data, using multiple field data patterns from an island hare population study to guide model development. A general and widely applicable approach to the pattern-oriented protocol for testing and developing ecological models of this kind was defined together with the development of the ODdox documentation protocol, a combination of the current ODD protocol for describing agent-based models and source-code documentation. The result is a detailed and yet accessible description of the processes included in the model. Application of the model to a comprehensive historical data set supported the hypothesis that interference competition is the primary population regulating factor in the absence of mammal predators in the brown hare, and that the effect works through reduced fecundity. With a clearly defined testing protocol and documentation, this in silico modelling approach has clear advantages for applications requiring integration of many factors, especially when spatio-temporal variability is important. Providing multi-facetted output which can be compared to real-world data allows the formulation and testing of varied hypotheses in ways not tractable to experimentation. In the case of the brown hare the results provide a new insight into population regulation and the causes of the declines.

Introducing students to professional software construction

It is widely accepted that there is more to software construction than basic programming skills. Professional software construction involves not only understanding some theoretical concepts, but also mastering appropriate tools and practices. In this paper, we present an undergraduate course in Software Construction and Maintenance , developed with the goal of introducing students to those key concepts, tools and practices. We first outline the content of that course, explaining how it fits within our undergraduate program. We then present a key element of that course-namely, its maintenance corpus along with its testing frameworks-used to concretely introduce students to various tools and practices, e.g., automatic test execution, build and configuration management, source code documentation, use of assertions, etc.

Scale economies and production function estimation for object-oriented software component and source code documentation size

In this study, we investigate the factors that influence the object-oriented (OO) component size and source code documentation. For multiple inputs and multiple outputs, we use data envelopment analysis to illustrate that non-linear variable returns to scale (VRS) economies exist for OO component size and source code documentation. The existence of non-linear variable returns to scale economies indicates that non-linear regression models will perform better than linear regression models. Using empirical data, we compare the performance of non-linear artificial neural network (ANN) forecasting model and linear regression model. Our results indicate that the ANN model performs well when VRS economies exist between multiple inputs and multiple outputs.

NCL: a C++ class library for interpreting data files in NEXUS format.

The NEXUS Class Library (NCL) is a collection of C++ classes designed to simplify interpreting data files written in the NEXUS format used by many computer programs for phylogenetic analyses. The NEXUS format allows different programs to share the same data files, even though none of the programs can interpret all of the data stored therein. Because users are not required to reformat the data file for each program, use of the NEXUS format prevents cut-and-paste errors as well as the proliferation of copies of the original data file. The purpose of making the NCL available is to encourage the use of the NEXUS format by making it relatively easy for programmers to add the ability to interpret NEXUS files in newly developed software. The NCL is freely available under the GNU General Public License from http://hydrodictyon.eeb.uconn.edu/ncl/ Documentation for the NCL (general information and source code documentation) is available in HTML format at http://hydrodictyon.eeb.uconn.edu/ncl/

Automating comments

This paper addresses the problem of source code documentation. Source code documentation has two components: the description of the statement and the description of the steps required to go from the specifications in natural language to programming language statements. We propose a model that provides a different mechanism for each form of documentation. A tool is used to implement and automate this approach. Results show that this approach provides a systematic and coherent mechanism for source code documentation. Productivity is increased and maintenance effort is greatly reduced.