Academic research code has a (well-deserved) reputation for being a mess. This is especially true in my area of pure math, as academia simply gives no weight or value to code quality of programming best practices.
Thinking about it more, I realize that I would like some more structure to the READMEs that I see in academic code. This is what I'm going with now.1 1I write this here also so that I can refer back to it next time I'm writing a README for some math code.
- Broad Description
- Give a title
- State a one-to-two sentence brief description, the elevator pitch.
- Link to the associated paper(s).
- Optionally, give keywords or MSC2020 codes for searchability.
- Optionally, briefly describe the results or highlights of the paper, maybe including graphics.
- Describe code requirements and installation/setup/running requirements.
Something equivalent to a
requirements.txtfile would be ideal, but is not always possible.
Also consider describing hardware necessary or used, if appropriate.
If additional configuration is required, note it here. 4. Describe the code structure and usage. How does one run the code?
If there are particular data formats for input or output, describe them as necessary. 5. Data (if appropriate).
If there is an associated dataset, describe it. Link to it if it's external. Give generation code if it's synthetic of computational.
Also describe the license for the data! 6. Give reproducibility notes. Are there any tips or tricks for getting things to run as expected? Is there an art, or is it straightforward? 7. If there are additional comments, give them.
I like to clarify that the repository is not accepting contributors, but the authors might appreciate collaborations. 8. State the code license. 9. Optionally, acknowledge funding sources.
I have not always done this in the past. But I should have!
Info on how to comment
To make a comment, please send an email using the button below. Your email address won't be shared (unless you include it in the body of your comment). If you don't want your real name to be used next to your comment, please specify the name you would like to use. If you want your name to link to a particular url, include that as well.
bold, italics, and plain text are allowed in comments. A reasonable subset of markdown is supported, including lists, links, and fenced code blocks. In addition, math can be formatted using
$(inline math)$or$$(your display equation)$$.Please use plaintext email when commenting. See Plaintext Email and Comments on this site for more. Note also that comments are expected to be open, considerate, and respectful.