{"id":1410,"date":"2022-10-27T15:36:06","date_gmt":"2022-10-27T15:36:06","guid":{"rendered":"https:\/\/www.lib.uiowa.edu\/data\/?page_id=1410"},"modified":"2026-02-18T23:07:57","modified_gmt":"2026-02-18T23:07:57","slug":"documenting-your-code","status":"publish","type":"page","link":"http:\/\/www.lib.uiowa.edu\/data\/share-and-preserve-your-code\/documenting-your-code\/","title":{"rendered":"Documenting Your Code"},"content":{"rendered":"<p><a href=\"#good\">Best Practices<\/a>\u00a0 |\u00a0 <a href=\"#api\">API Documentation<\/a>\u00a0 |\u00a0 <a href=\"#tools\">Helpful Tools<\/a><\/p>\n<p>Documenting your code happens throughout your project. It helps others understand what you\u2019ve done, and makes your own life easier when you return to or reuse the code. <a href=\"https:\/\/www.nature.com\/articles\/s41597-022-01710-x\" target=\"_blank\" rel=\"noopener\">Well-documented, preserved, and shared code is aligned with FAIR principles. <i class=\"fas fa-external-link-alt\"> <\/i><\/a><\/p>\n<p>Below are some suggestions. Documentation is helpful for your own unshared projects, but especially when you <a href=\"https:\/\/www.lib.uiowa.edu\/data\/share\/share-and-preserve-your-code\/\" target=\"_blank\" rel=\"noopener\">deposit code in a repository<\/a>.<\/p>\n<p>See also <a href=\"https:\/\/journals.plos.org\/ploscompbiol\/article?id=10.1371\/journal.pcbi.1005510#sec005\">Good enough practices for software documentation<\/a> (<em>PLOS Computational Biology<\/em>)<\/p>\n<h3 id=\"good\">Best Practices<\/h3>\n<ul>\n<li>Apply conventions for your specific programming language such as those for:\n<ul>\n<li>Naming<\/li>\n<li>Layout<\/li>\n<li>Commenting<\/li>\n<li>Declarations<\/li>\n<\/ul>\n<\/li>\n<li>Create a README for your code (<a href=\"https:\/\/www.lib.uiowa.edu\/data\/files\/2022\/10\/README_Template-2.txt\" target=\"_blank\" rel=\"noopener\">this template<\/a> may be useful) in .txt or .md (Markdown) format.<br \/>\nA README might include the following:<\/p>\n<ul>\n<li>Project title and description\n<ul>\n<li>What was the overall goal of the project? What does your application do? What technologies did you use?<\/li>\n<\/ul>\n<\/li>\n<li>Instructions for setup\/installation\n<ul>\n<li>What are the steps for installing and running your project?<\/li>\n<\/ul>\n<\/li>\n<li>A quick start guide that shows how to use it\n<ul>\n<li>How can others use the project? Can you include screenshots to showcase what users should expect?<\/li>\n<\/ul>\n<\/li>\n<li>Credits for all contributors\n<ul>\n<li>Who collaborated on the project?<\/li>\n<\/ul>\n<\/li>\n<li>Licensing info\n<ul>\n<li>What <a href=\"https:\/\/www.lib.uiowa.edu\/data\/share-and-preserve-your-code\/software-and-code-licenses\/\" target=\"_blank\" rel=\"noopener\">license governs its use<\/a>?<\/li>\n<li>What can others do or not do with your project?<\/li>\n<\/ul>\n<\/li>\n<li>How should others cite your code when they use it?\n<ul>\n<li>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.<\/li>\n<li>If you deposited it in a repository, what DOI is associated with this work?<\/li>\n<li>Provide a citation so others know how you want it cited<\/li>\n<\/ul>\n<\/li>\n<li>Contact info\n<ul>\n<li>What\u2019s your email address and\/or <a href=\"https:\/\/orcid.org\/\" target=\"_blank\" rel=\"noopener\">ORCID <i class=\"fas fa-external-link-alt\"> <\/i><\/a>?<\/li>\n<li>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.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<p style=\"padding-left: 40px\">The following video provides an overview of README files for software and code.<\/p>\n<p><!-- aria-description=\"This video provides an introduction to README files for software and code.\" --><\/p>\n<div class=\"video-fullwidth-16-9\"><iframe title=\"README Files for Software and Code\" src=\"https:\/\/uicapture.hosted.panopto.com\/Panopto\/Pages\/Embed.aspx?id=a2570318-39eb-4c7f-94f0-b33d010c86b0&amp;autoplay=false&amp;offerviewer=true&amp;showtitle=false&amp;showbrand=false&amp;captions=false&amp;interactivity=all\" allowfullscreen=\"allowfullscreen\"><\/iframe><\/div>\n<ul>\n<li>Allow an issue tracker to follow bugs, feedback, and fixes.<\/li>\n<li>For code version documentation, consider:\n<ul>\n<li>What are the major edits you did with each version of the code?<\/li>\n<li>Did you follow <a href=\"https:\/\/www.lib.uiowa.edu\/data\/manage\/version-control\/\" target=\"_blank\" rel=\"noopener\">best practices<\/a> for naming each version?<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<h3 id=\"api\">Documentation for APIs<\/h3>\n<ul>\n<li>For APIs, consider describing:\n<ul>\n<li>What does each function do?<\/li>\n<li>What are each function\u2019s inputs and input types?<\/li>\n<li>What are each function\u2019s outputs and output types?<\/li>\n<li>What errors might someone encounter?<\/li>\n<li>What are the methods and attributes for each object?<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<h3 id=\"tools\">Tools for documenting code<\/h3>\n<table class=\"simple-table\" style=\"width: 100%;height: 326px\">\n<tbody>\n<tr style=\"height: 66px\">\n<th style=\"width: 24.7503%;height: 62px\">Tool<\/th>\n<th style=\"width: 74.3618%;height: 62px\">Languages Supported<\/th>\n<\/tr>\n<tr style=\"height: 24px\">\n<td style=\"width: 24.7503%;height: 24px\"><a href=\"https:\/\/github.com\/doctest\/doctest\" target=\"_blank\" rel=\"noopener\">Doctest<\/a><\/td>\n<td style=\"width: 74.3618%;height: 24px\">C++<\/td>\n<\/tr>\n<tr style=\"height: 24px\">\n<td style=\"width: 24.7503%;height: 24px\"><a href=\"https:\/\/doxygen.nl\/\" target=\"_blank\" rel=\"noopener\">Doxygen<\/a><\/td>\n<td style=\"width: 74.3618%;height: 24px\">C, C++, C#, Fortran, IDL, Java, MATLAB (with <a href=\"https:\/\/doxygen.nl\/helpers.html#doxfilt_matlab\" target=\"_blank\" rel=\"noopener\">an added filter <i class=\"fas fa-external-link-alt\"> <\/i><\/a>) PHP, Python<\/td>\n<\/tr>\n<tr style=\"height: 24px\">\n<td style=\"width: 24.7503%;height: 24px\"><a href=\"https:\/\/www.mathworks.com\/help\/matlab\/creating-help.html\" target=\"_blank\" rel=\"noopener\">MATLAB Toolbox<\/a><\/td>\n<td style=\"width: 74.3618%;height: 24px\">MATLAB<\/td>\n<\/tr>\n<tr style=\"height: 48px\">\n<td style=\"width: 24.7503%;height: 48px\"><a href=\"https:\/\/www.naturaldocs.org\/\" target=\"_blank\" rel=\"noopener\">Natural Docs<\/a><\/td>\n<td style=\"width: 74.3618%;height: 48px\">ActionScript, Ada, Assembly, C, C++, C#, Fortran, Java, JavaScript, Lua, Makefiles, Pascal\/Delphi, Perl, PHP, PL\/SQL, Python, R, Ruby, Tcl, Text Files, Visual Basic<\/td>\n<\/tr>\n<tr style=\"height: 24px\">\n<td style=\"width: 24.7503%;height: 24px\"><a href=\"https:\/\/pypi.org\/project\/numpydoc\/\" target=\"_blank\" rel=\"noopener\">NumpyDoc<\/a><\/td>\n<td style=\"width: 74.3618%;height: 24px\">Python<\/td>\n<\/tr>\n<tr style=\"height: 24px\">\n<td style=\"width: 24.7503%;height: 24px\"><a href=\"https:\/\/rmarkdown.rstudio.com\/\" target=\"_blank\" rel=\"noopener\">R Markdown<\/a><\/td>\n<td style=\"width: 74.3618%;height: 24px\">Python, R, SQL<\/td>\n<\/tr>\n<tr style=\"height: 24px\">\n<td style=\"width: 24.7503%;height: 24px\"><a href=\"https:\/\/www.sphinx-doc.org\/en\/master\/\" target=\"_blank\" rel=\"noopener\">Sphinx<\/a><\/td>\n<td style=\"width: 74.3618%;height: 24px\">Python, MATLAB (with <a href=\"https:\/\/pypi.org\/project\/sphinxcontrib-matlabdomain\/\" target=\"_blank\" rel=\"noopener\">an added extension <i class=\"fas fa-external-link-alt\"> <\/i><\/a>)<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n","protected":false},"excerpt":{"rendered":"<p>Best Practices\u00a0 |\u00a0 API Documentation\u00a0 |\u00a0 Helpful Tools Documenting your code happens throughout your project. It helps others understand what you\u2019ve done, and makes your own life easier when you [&hellip;]<\/p>\n","protected":false},"author":163,"featured_media":0,"parent":1304,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"pagetpl-data.php","meta":{"footnotes":"","_links_to":"","_links_to_target":""},"categories":[],"tags":[34,58,35,57,32],"class_list":["post-1410","page","type-page","status-publish","hentry","tag-readme","tag-scripts","tag-sharing-code","tag-software","tag-code","","data","wp-json","wp","v2","pages","1410"],"_links":{"self":[{"href":"http:\/\/www.lib.uiowa.edu\/data\/wp-json\/wp\/v2\/pages\/1410","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/www.lib.uiowa.edu\/data\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"http:\/\/www.lib.uiowa.edu\/data\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"http:\/\/www.lib.uiowa.edu\/data\/wp-json\/wp\/v2\/users\/163"}],"replies":[{"embeddable":true,"href":"http:\/\/www.lib.uiowa.edu\/data\/wp-json\/wp\/v2\/comments?post=1410"}],"version-history":[{"count":47,"href":"http:\/\/www.lib.uiowa.edu\/data\/wp-json\/wp\/v2\/pages\/1410\/revisions"}],"predecessor-version":[{"id":3192,"href":"http:\/\/www.lib.uiowa.edu\/data\/wp-json\/wp\/v2\/pages\/1410\/revisions\/3192"}],"up":[{"embeddable":true,"href":"http:\/\/www.lib.uiowa.edu\/data\/wp-json\/wp\/v2\/pages\/1304"}],"wp:attachment":[{"href":"http:\/\/www.lib.uiowa.edu\/data\/wp-json\/wp\/v2\/media?parent=1410"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/www.lib.uiowa.edu\/data\/wp-json\/wp\/v2\/categories?post=1410"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/www.lib.uiowa.edu\/data\/wp-json\/wp\/v2\/tags?post=1410"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}