Guidelines and script for the generic documentation of source code implemented in various programming languages (bash/Perl/Python/R/Matlab/SAS/Stata/DOS/…).

Description

An appropriate documentation will enable:

• users to efficiently run and (re)use a program/code,
• developers to maintain, share, extend, and migrate a program.

Say it otherwise, it should address the needs of all different produsers’ profiles. For that reason, it will be made available not only as an inline documentation (visible by those who actually implement the code, e.g. through comments in the code), but as a portable document (visible by those who run the code, e.g. through a browsable interface like html) as well. To do so, we suggest to adopt a common way for describing and documenting source code/programs regardless of the platform (language, software) used for the implementation. The solution we propose in practice (see our motivation here) is the following:

• an “inline” documentation is systematically inserted in the header (e.g., top of the program file storing a macro, a function, etc…),
• this documentation appears as comments inside the programs (e.g., in between /* and */ marks for many languages),
• the human-readable markdown language is adopted for writing the source code documentation,
• a (bash) script, namely src2mddoc.sh, for the automatic extraction of the formatted documentation header from the source files,
• the documentation generator Doxygen is used to generate a user-friendly browsable “online” documentation.

Rather than describing IT tools, the purpose of the documentation is to describe the underlying statistical processes. Therefore, it is important that the documentation does not restrict to a single programming language or software, but instead supports various different implementations. In this aspect, we hereby provide with the common guidelines and templates to inline document:

• SAS, R, Stata, Matlab, Perl and Python programs/functions,
• bash and DOS scripts.

as well as the tool to automatically extract the inline documentation, and the commands to generate an online document that merges the different documentations.

Table of Contents

• rationale: Rationale behind these choices (of documentation language, of documentation generator,…) that have been made.
• guidelines: Set of guidelines used for the documentation of various programs (function/macro/script/…) in different languages.
  • generic template.
  • SAS rules.
  • Stata rules.
  • R rules.
  • Python rules.
  • bash rules.
  • Matlab rules.
  • DOS rules.
• usage: Usage of the script for the extraction of the documentation.
• examples: Examples of generation of online browsable documentation.

Notes

1. The approach proposed herein is adapted to the documenting of stand-alone programs and processes. It can be can easily be extended (e.g., slightly adapting the guidelines and tools) to support other software/programing languages.
2. The solution proposed addresses the needs of all produsers’ profiles (i.e., both users who aim at running and (re)using a program/code, and developers who want to maintain, share, extend, and migrate a program).

About

This material aims at supporting the development, sharing and reuse of open IT components, e.g., deployed in production environment, and ensuring complete transparency of in-house computational resources, e.g. regardless of the platform used for the implementation as presented in:

• Grazzini J. and Lamarche P. (2017): Production of social statistics… goes social!, in Proc. New Techniques and Technologies for Statistics.
• Grazzini J. and Pantisano F. (2015): Collaborative research-grade software for crowd-sourced data exploration: from context to practice - Part I: Guidelines for scientific evidence provision for policy support based on Big Data and open technologies, Publications Office of the European Union, doi:10.2788/329540.

Notice

Copyright (c) 2017, J.Grazzini, European Commission.

Licensed under European Union Public License.