Coding Best Practices

Coding Best Practices

Submitted models are expected to follow coding best practices, including comments, variable names, formatting, and documentation.

Recommended Docstrings Formats 

All are mostly based on reStructuredText (reST)

MATLAB

• Adding help for your program https://www.mathworks.com/help/matlab/matlab_prog/add-help-for-your-program.html   

Python/R 

• Google’s  
• Numpydoc 
• roxygen2 (R)  
• pyment (lib to transform between the formats above) 

C/C++/C# +

• Doxygen https://developer.lsst.io/cpp/api-docs.html 
• How To Document and Organize Your C++ Code: http://www.edparrish.net/common/cppdoc.html

Code Style Guidelines

MATLAB

• Matlab Style Guidelines 2.0 https://www.mathworks.com/matlabcentral/fileexchange/46056-matlab-style-guidelines-2-0
  • http://www.datatool.com/downloads/MatlabStyle2%20book.pdf 
  • https://sites.google.com/site/matlabstyleguidelines/home

C/C++/C#/Fortran

• Google’s https://google.github.io/styleguide/cppguide.html
• NASA https://mechatronics.me.wisc.edu/labresources/DataSheets/NASA-GSFC_C_Programming_Styles-94-003.pdf 
• NASA’s ASTG https://modelingguru.nasa.gov/servlet/JiveServlet/previewBody/1439-102-9-6255/ASTG_Coding_Standards_v1.7.pdf 

Python

• PEP 8 – Style Guide for Python Code https://www.python.org/dev/peps/pep-0008/
• Google  https://google.github.io/styleguide/pyguide.html
• NASA https://modelingguru.nasa.gov/servlet/JiveServlet/previewBody/1439-102-9-6255/ASTG_Coding_Standards_v1.7.pdf 

Others  

• Google Style Guides https://google.github.io/styleguide/
  • https://github.com/google/styleguide
• NASA’s ASTG https://modelingguru.nasa.gov/servlet/JiveServlet/previewBody/1439-102-9-6255/ASTG_Coding_Standards_v1.7.pdf 

Documentation Tools

• Matlab Report Generator (Matlab) https://www.mathworks.com/help/rptgen/index.html 
• Doxygen (C, C++, C#, Python, PHP…) https://www.doxygen.nl/manual/starting.html
• Sphinx (Python, Matlab) 
• https://www.sphinx-doc.org/en/master/usage/quickstart.html
  • The Official Python docs https://docs.python.org/3/ use this tool 
  •  Matlab add-on https://pypi.org/project/sphinxcontrib-matlabdomain/ 
• HDoc (C++) https://hdoc.io/
• PDoc (Python) https://pdoc.dev/
• Docutils (Python) https://docutils.sourceforge.io/
• Pandoc (General text) https://pandoc.org/
• Rippledoc (General) http://www.unexpected-vortices.com/sw/rippledoc/
• Github Pages (documentation site, off-topic)
  • https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages
• More https://wiki.python.org/moin/DocumentationTools