University Libraries - Research Data Services

Best Practices  |  API Documentation  |  Helpful Tools

Documenting your code happens throughout your project. It helps others understand what you’ve done, and makes your own life easier when you return to or reuse the code. Well-documented, preserved, and shared code is aligned with FAIR principles.

Below are some suggestions. Documentation is helpful for your own unshared projects, but especially when you deposit code in a repository.

See also “good enough” practices for software documentation (from PLOS Computational Biology)

Best Practices

• Allow an issue tracker to follow bugs, feedback, and fixes.
• Apply conventions for your specific programming language such as those for:
  • Naming
  • Layout
  • Commenting
  • Declarations
• Create a brief README for your code (this template may be useful) that includes:
  • Project title and description
    • What was the overall goal of the project? What does your application do? What technologies did you use?
  • Instructions for setup/installation
    • What are the steps for installing and running your project?
  • A quick start guide that shows how to use it
    • How can others use the project? Can you include screenshots to showcase what users should expect?
  • Credits for all contributors
    • Who collaborated on the project?
  • Licensing info
    • What license governs its use?
    • What can others do or not do with your project?
  • How should others cite your code when they use it?
    • Have you deposited a copy of the software in Zenodo or another repository such as IRO?
    • If you did, what DOI is associated with this work?
    • Provide a citation so others know how you want it cited
  • Contact info
    • What’s your email address and/or ORCID ?
    • If you are looking for more contributors, make it clear that you welcome contributors and point them to the license and ways they can help.
• For code version documentation, consider:
  • What are the major edits you did with each version of the code?
  • Did you follow best practices for naming each version?

Documentation for APIs

• For APIs, consider describing:
  • What does each function do?
  • What are each function’s inputs and input types?
  • What are each function’s outputs and output types?
  • What errors might someone encounter?
  • What are the methods and attributes for each object?

Tools for documenting code