MolSSI
  • People
    • Board of Directors
    • Science & Software Advisory Board
    • MolSSI Software Scientists
    • MolSSI Associates
  • Fellowships
    • The MolSSI Software Fellowship Program
    • All MolSSI Software Fellows
    • 2021-A Seed Software Fellows
    • 2020-B and COVID-19 Seed Software Fellows
    • 2020-B Investment Software Fellows
    • 2020-A Seed Software Fellows
    • 2020-A Investment Software Fellows
  • Workshops
    • 2020
      • Open Source Software for Rare-Event Sampling Strategies
      • MolSSI/BioExcel Workshop on Workflows in Biomolecular Simulations
      • Biennial Conference on Chemical Education (BCCE)
      • MolSSI Driver Interface (MDI)
    • 2019
      • Stochastic Approaches to Electronic Structure Calculations
      • Software for Advanced Potential Energy Surfaces
      • Summer School and Workshop on Parallel Computing in Molecular Sciences
      • The Open Molecular Science Cloud
      • Molecular Dynamics Software Interoperability
      • Rovibrational Molecular Spectroscopy
      • Machine Learning and Chemistry: Challenges on the Way Forward
      • A Science Gateway for Atomic and Molecular Physics
    • 2018
      • Science Gateways Community Institute
      • NSF SSE/SSI PIs Workshop
      • Modular Software Infrastructure for Excited State Dynamics
      • Tinker Modeling Software
      • Python for Quantum Chemistry and Materials Simulation
      • Solving or Circumventing Eigenvalue Problems in Electronic Structure Theory
      • Summer School and Workshop Parallel Computing in Molecular Sciences
      • Workflows in Biomolecular Simulations
    • 2017
      • Computational Materials Science
      • Biomolecular Simulation
      • Core Software Blocks in Quantum Chemistry
      • Interoperability
      • Excited States
      • Coding Solvation
      • Best Practices in Molecular Simulation
      • Biomolecular Workflows
      • Quantum Mechanics Schema
    • 2016
      • Cyberinfrastructure and the Molecular Sciences
  • Education
    • MolSSI Education Resources
    • MolSSI Best Practices
    • Summer Schools
    • Coding Workshop @ MERCURY
  • News & Events
  • Software
    • Software Projects
    • COVID-19 Hub
    • MolSSI@Github
    • Basis Set Exchange
    • MolSSI Integral Reference Project
    • QCArchive
    • QCSchema
    • MolSSI Driver Interface
    • CMS Cookiecutter
  • Resources
    • Frequently Asked Questions (FAQs)
    • Publications from the MolSSI
    • Community Code Database
    • MolSSI Community Code Partners
    • Job Opportunities in the Molecular Sciences
    • Requesting a Letter of Collaboration
  • Subscribe

Best Practices

MolSSI best practices provide a starting point to get into software development operations to ensure that your code is reliable and reproducible while decreasing long-term maintenance requirements, increasing long-term viability, and allowing others to work on your code base to assist your ow efforts. Before starting into MolSSI best practice one must first think about the user base of a given project whether this is a project only used by yourself, within a small group, or a large community project. If your project is small and personal you may want to consider each topic in detail before implementing while for large community projects each topic is quite crucial.

MolSSI’s best practices center around the following pillars:

Version Control

Version control keeps a complete history of your work on a given project. It facilitates collaboration on projects where everyone can work freely on an part of the project without overriding others’ changes. You can move between past versions and rollback when needed, nothing is lost. Also, you can review the history of your project through commit messages that describe each added change and see what exactly has changed in the contents. You can see who made the changes and when it happened.

This is greatly beneficial whether you are working independently or within a team.

  • Recommended Hosting Service: GitHub
  • Other hosting Services: GitLab, BitBucket

Novice Tutorials:

  • Software Carpentry Version Control with Git
  • GitHub 15 Minutes to Learn Git
  • Git Commit Best Practices

Intermediate:

  • Git Workflows
  • Migration from SVN to Git

Testing and Code Coverage

Software should be tested regularly throughout the development cycle to insure correct operation. Thorough testing is typically an afterthought, but for larger projects it can be essential for ensuring changes in some parts of the code do not negatively affect other parts.

Two main types of testing are strongly encouraged

  • Regression tests – given a known input, does the software correctly and consistently return the correct values?
  • Unit tests – Similar to general testing, except testing is done on much smaller units (such as single functions or classes). This is helpful for catching errors in uncommonly-used parts of the code which may be skipped in general testing. Unit tests can be added as new features are added, resulting in better code coverage.

Recommended:

  • Python: PyTest
  • C/C++/Fortran: CTest

Tutorials:

  • PyTest Introduction

Continuous Integration

Continuous integration (CI) automatically runs builds your codes and run your tests on a variety of different platforms. Typically this may be run when new code is committed or before merging experimental code into the main repository. CI useful for catching bugs before they reach your end users, and for testing on platforms that are not available to every developer.

Most CI software and services have webhooks for integration github.

Examples of CI Software/Services:

  • Web-based services
    • Travis CI (Linux/Mac OSX)
    • Circle CI (Linux)
    • Appveyor (Windows)
  • Self Hosted
    • Jenkins
    • Buildbot
  • Web based with own hardware
    • Distelli

Examples of projects using CI:

  • MolSSI Integral Reference Project (C code with Travis)
  • Energy Exchange (Python with Appveyor and Travis)
  • Basis Set Exchange (Python with Travis)

Code Style

Code style is important so that new developers can quickly read and understand new code. While code style is typically quite personal, languages often have at least a few dominant coding styles which are familiar to most programmers in that language. Automatic formatting can enforce a particular coding style, and are often configurable for each project.

  • Python: YAPF (enforces PEP8)
  • C/C++: clang-format, astyle

Example of a coding style guides:

  • Python Style Guide
  • Google C++ Style Guide

Documentation

Documentation must be provided to allow for use, development, and maintenance of the code. Documentation is often overlooked by developers since it is tedious and boring, however good documentation is an extremely good habit to develop.

The documentation typically involves several components:

  • Build requirements and dependencies (if applicable)
  • How to compile/build/test/install
  • How to use the software (through the API or through inputs)
  • Some examples

Another aspect of documentation is code documentation. This is very important for further development and maintenance, including by yourself in the future. This typically includes documenting various internal files, functions, and classes; what pieces of code do; and most importantly, the reasoning behind some decisions as to why some code was written a particular way.

Documentation should be kept up to date with changes in the code, which is not an easy task for large, fast-moving codebases. However, slightly out-of-date documentation is generally preferable to no documentation.

It is recommended that the examples provided within the documentation are compiled and/or run regularly (if possible, as part of the testing of the software) to ensure that it does not become neglected and out-of-date, confusing users.

Popular documentation packages:

  • C/C++/Fortran – Doxygen
  • Python – Sphinx, Read The Docs

Examples of good documentation:

  • Pybind11 – A C++/Python binding module
  • Arb – Arbitrary precision math library
  • Eigen – C++ Matrix math library

Build Systems

Generally, at least part of a lot of software must be compiled. Doing this in a clean (and possibly cross-platform) way is not trivial.

However, having a somewhat standard build system makes uptake by new users and developers much easier and makes it more likely that the code will be maintained in the future. Therefore, use of common build systems is encouraged. For most compiled C/C++/Fortran code encountered in computational chemistry, CMake is recommended.

  • CMake tutorial
  • CMake book
  • CMake Examples
  • More CMake Resources

Best Practices in Software Design

Software quality depends on many factors such as: Functionality, usability, performance, reliability, portability, interoperability, scalability, and reusability (see full description here).

There are many aspects that contribute to a good design and to the quality of your software. An important one is to follow the best practices and give thoughts to the design of your software. Lucky, many experienced programmers have developed best practices over a substantial period of time. Those best practices can help inexperienced developers to learn software design easily and quickly.

SOLID:

The first things you can learn that will immediately improve the quality of software is to follow the  the SOLID Principles of Software Design. Following those 5 principles will results in a more understandable, flexible and maintainable code.  You can read more here:

  • Dev IQ: The SOLID principles of Object Oriented Design
  • The Team Coder: SOLID Principles of Software Design by Examples

Design Patterns:

Design Patterns are well-thought-of, reusable solutions to common recurring problems that developer face during software development. They are considered a common terminology between experience developers. Design Patterns are general and can be applied to any programming language. It’s also highly encouraged to use Object Oriented Programming (correctly) in large-scale projects. The following are some reference to get you started.

  • Python Design Patterns: For Sleek And Fashionable Code
  • Design Pattern in Python (Github examples)
  • A General tutorial on Design Patterns

Object Oriented Programming (OOP):

It’s also highly encouraged to use Object Oriented Programming (correctly) in large-scale projects.

  • Object oriented tutorial (python 2)
  • Object oriented tutorial (python 3)
  • Gillius’s Programming (C++)

External Resources

Examples

  • MolSSI Python CookieCutter

Additional Links

  • MolSSI Education GitHub
  • The Netherlands eScience Center Guide
  • Better Scientific Software
  • Chodera Lab Software Primer

Upcoming Events

View All Events



Contact Us

E: info@molssi.org
P: (540) 231-4457
Location: 1880 Pratt Drive, Suite 1100
Blacksburg, VA 24060

Subscribe to our mailing list

Board of Directors

T. Daniel Crawford (Virginia Tech)
Cecilia Clementi (Rice University)
Robert Harrison (Stony Brook University)
Teresa Head-Gordon (U.C. Berkeley)
Shantenu Jha (Rutgers University)
Anna Krylov (U. Southern California)
Theresa Windus (Iowa State University)
Dominika Zgid (U. Michigan)

Connect with us

Visit Us On FacebookVisit Us On LinkedinVisit Us On Twitter

NSFLogoThe MolSSI is supported by the U.S. National Science Foundation through grant number OAC-1547580.

© 2020 The Molecular Sciences Software Institute, Designed by FourDesign
Close Window

Loading, Please Wait!

This may take a second or two. Loading, Please Wait!