<story><title>Simple rules for documenting scientific software</title><url>https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006561</url></story><parent_chain></parent_chain><comment><author>acidburnNSA</author><text>I manage a team of power plant design engineers writing complex scientific HPC software, mostly in Python (which drives Fortran 77 codes behind the scenes, among other things). It&amp;#x27;s been a long haul but through the years we&amp;#x27;ve learned a lot of good lessons and are pretty productive at what I consider at least moderately good code. Everyone starts off by reading Clean Code and taking basic proficiency training. We know to try to make code speak for itself because, as we&amp;#x27;ve all seen many times, comments lie. We&amp;#x27;ve slowly learned from the software engineering community how to set up things like Jenkins for CI, black for Python code auto-formatting, Phabricator for revision control policy and code review. We&amp;#x27;re writing docs in rst with sphinx, watching coverage, and getting pylint 10&amp;#x2F;10. We&amp;#x27;re waking up to the wonders of static types.&lt;p&gt;Mandatory code review has turned out to be a great way to train newbies, write better code, and make sure code is understandable to at least one other person. It&amp;#x27;s been an investment (it&amp;#x27;s slowww) but I still think it pays dividends. That&amp;#x27;s what I&amp;#x27;d add to this advice. And I&amp;#x27;d tone down the comments focus. Comment only when you fail to express yourself clearly in the code.</text></comment>
<story><title>Simple rules for documenting scientific software</title><url>https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1006561</url></story><parent_chain></parent_chain><comment><author>hprotagonist</author><text>A really great idea: put DOIs in your function documentation.&lt;p&gt;Writing things like:&lt;p&gt;&lt;i&gt;Implements equation 3.2 of Foo et. al. (2005), doi:10.2.3&amp;#x2F;baz&lt;/i&gt;&lt;p&gt;has saved me no end of pain in the past.</text></comment>