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. These are helpful for unshared projects, but especially when you deposit code in a repository.

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
• Implement “good enough” practices for software documentation (from PLOS Computational Biology)
• Create a brief README for your code that includes (see template screenshot below):
  • 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?
    • 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?
• 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

You may find this template useful as you create your README.

Write separate documentation for APIs

• For APIs, consider:
  • 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