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 (PLOS Computational Biology)

Best Practices

• Apply conventions for your specific programming language such as those for:
  • Naming
  • Layout
  • Commenting
  • Declarations
• Create a README for your code (this template may be useful) in .txt or .md (Markdown) format.
  A README might include the following:
  • 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?
    • Deposit a copy of the software in Zenodo or another repository such as IRO, to preserve it and make it easier to find and cite.
    • If you deposited it in a repository, 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.
• Allow an issue tracker to follow bugs, feedback, and fixes.
• 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