IQSS Best Practices for Software Development

How to use the Best Practice

The Institute for Quantitative Social Science (IQSS), Harvard University Best Practices for Software Development are intended as a general guide to developing software that is:

• robust,

• user-friendly,

• persistent,

• attributable,

• enables reproducible research.

The extent to which they apply to any specific project will vary depending on the software's purpose. Nonetheless, considering these suggestions and coming up with thoughtful reasons for why they do or do not apply to your software, when you begin a software project can improve its quality and usefulness.

The best practices in this document are intended to be applicable to statistical software development regardless of the programming language it is written in. Language specific guidelines based on these best practices are documented elsewhere in this repository.

Best practices

Social science statistical software is more likely to achieve the aims listed above if they have the following characteristics:

1.) Are informatively documented

• Documentation is written as close to the source code as possible, e.g. using Doxygen or a Doxygen-like markup.

• Documentation is comprehensive and written in an approachable style.

• Documentation is accessible both alongside the software and on a website.

• Documentation is automatically generated for each version, in machine and human readable formats.

• Versions are numbered using semantic versioning.

• All changes made to the software are documented in a "changelog".

2.) Have an open source license

• For example, GPL (3).
• See Choose a License for information on how to choose a software license.

3.) Are comprehensively and automatically tested

4.) Are developed using version control

• For example, but not limited to, git.

5.) Are developed in the open using tools and standards that enable full source code discovery, exploration, and external contributions

• For example, but not limited to, GitHub.

• The development service should include facilities for making public bug reports. If security concerns are important, a private channel for bug reports should also be available and clearly documented.

6.) Are clearly citeable

• {SOFTWARE CITATION}

7.) Uses an IQSS Report Card to report their minimal compliance with these Best Practices

Language-specific Best Practices

The tools for implementing the Best Practices are often different depending on the programming language used to create the statistical software.

For packages written in the R language please see: [R IQSS Best Practices](best_practices_per_language/r_best_practices.md).