From f8c9747d3b6425b420839ff06931b63692318f03 Mon Sep 17 00:00:00 2001
From: Blaise Thompson <blaise@untzag.com>
Date: Thu, 5 Apr 2018 09:47:06 -0500
Subject: 2018-04-05 09:47

---
 software/chapter.tex | 66 ++++++++++++++++++++++++++++++++++------------------
 1 file changed, 44 insertions(+), 22 deletions(-)

(limited to 'software/chapter.tex')

diff --git a/software/chapter.tex b/software/chapter.tex
index b52764b..b235ecb 100644
--- a/software/chapter.tex
+++ b/software/chapter.tex
@@ -1,6 +1,4 @@
-% TODO: add StoddenVictoria2016a (Enhancing reproducibility for computational methods)
-
-\chapter{Software}
+\chapter{Software} \label{cha:sof}
 
 \begin{dquote}
   The following guidelines are to be used in the documentation of all software developed in the
@@ -55,8 +53,8 @@ basic software engineering concepts.  %
 This is in part due to the their general lack of formal training in programming and software
 development. \textcite{HannayJoErskine2009a} found that over 90\% of scientists learn software
 development through `informal self study', while \textcite{SegalJudith2004a} mentions that
-``[scientists] do not describe themselves as software developers and have little formal education
-or training in software development''. HannayJoErskine2009a agrees. JoppaLucasN2013a aggrees.
+\emph{``[scientists] do not describe themselves as software developers and have little formal
+  education or training in software development''}.
 
 This lack of training is not in-and-of-itself a problem.  %
 After all, academic scientists are required to be ``do-it-yourself''ers in many contexts for which
@@ -105,7 +103,15 @@ Software development ``by-and-for'' scientists poses unique challenges.  %
 In this section, I attempt to summarize the literature about these challenges, with a focus on
 those challenges that I have found most relevant.  %
 
-\textbf{Extensibility.}  % TODO: cite
+\textbf{``End-user developers.''} \cite{SegalJudith2005a, HannayJoErskine2009a, JoppaLucasN2013a}
+% TODO: see Joppa ref 17, 21 22
+Typically the developers of scientific software are not trained software developers.  %
+This is perfectly appropriate, because scientific software development typically requires a large
+amount of domain knowledge that only ``end-users'' possess.  %
+Software development practices may not be valued in a scientific environment.  %
+
+\textbf{Extensibility.} \cite{SegalJudith2005a, CarverJeffreyC2007a, HannayJoErskine2009a,
+  PrabhuPrakash2011a}
 Many traditional software development paradigms demand an upfront articulation of goals and
 requirements.  %
 This allows the developers to carefully design their software, even before a single line of code is
@@ -122,13 +128,18 @@ of researchers and a contracted team of software engineers.  %
 
 \end{dquote}
 
-PrabhuPrakash2011a---lots of good stuff under ``Scientists do not rigorously test their programs''
+Scientific software is \emph{explorative}, and it needs to be flexible and extendable.  %
+Scientific software developers cannot know what will be required before they set out to try.  %
+This is probably the most fundamental challenge in such projects, and a big part of why science
+cannot simply ``contract out'' a large part of its software development needs.  %
+Sometimes, a scientific problem is worked out though the iterative process of developing software
+to solve it.  %
 
-\textbf{Lifetime.}
-PrabhuPrakash2011a--- subsection ``long history of software development''
-Challenges with portability, and updating to ``modern standards''.
+\textbf{Lifetime.} \cite{CarverJeffreyC2007a, PrabhuPrakash2011a}
+Many scientific software projects have long life cycles, measured in decades or more.  %
+Challenges with portability, and updating to ``modern standards''.  %
 
-\textbf{Maintenance}
+\textbf{Maintenance.} \cite{PrabhuPrakash2011a}
 Scientific software, especially software maintained by graduate students, tends to be very hard to
 maintain.  %
 This problem is compounded by the long lifetime of such software, and the poorly defined
@@ -138,9 +149,17 @@ written by generation upon generation of student.  %
 Worse, software is sometimes abandoned or left untouched to become a crucial but arcane component
 of a scientific research project.  %
 
-\textbf{Optimization}
-PrabhuPrakash2011a: ``scientists do not optimize for the common case'', ``scientists are unaware of
-parallelization paradigms''
+\textbf{Testing.} \cite{SandersRebecca2008a, PrabhuPrakash2011a}
+Testing is a huge part of software development practices, but many researchers do not engage in
+sufficient testing of their software...  %
+The issue of testing is also consistent with the system of peer review...
+Software is not typically peer reviewed...
+Especially for domain-specific computational software, determining the ``correct outcome'' to test
+against is often infeasible.  %
+
+\textbf{Optimization.} \cite{PrabhuPrakash2011a}
+Scientists do not optimize for the common case.  %
+Scientists are unaware of parallelization paradigms.  %
 
 \section{Good-enough practices}  % ================================================================
 
@@ -151,7 +170,7 @@ In this section, I attempt to very quickly summarize my personal perspective on
 software development good---with citations to literature that supports each idea.  %
 These practices are not, generally, \emph{extra work}.  %
 In fact, many of them save massive amounts of time and effort in the long \emph{and} short run,
-when properly applied.  %
+when properly applied. \cite{WilsonGreg2006a}  %
 
 \textbf{Do not reinvent.} \cite{WilsonGreg2017a}  %
 Before you sit down and implement a piece of software, stop!  %
@@ -172,7 +191,7 @@ that accepts a set of arguments.  %
 If your software package grows to contain multiple files, make those files modular.  %
 As a general rule, once you have two classes you need multiple files.  %
 
-\textbf{Choose good data formats.} \cite{WilsonGreg2017a}  %
+\textbf{Choose good data formats.} \cite{BaxterSusanM2006a, WilsonGreg2017a}  %
 Choose a non-proprietary format if at all possible---remember: you yourself might not have access
 to the proprietary software in 10 years.  %
 Choose plain text if you can.  %
@@ -185,7 +204,7 @@ Make sure that it is clear what each piece of data means.  %
 For tabular data, use headers.  %
 Don't forget units.  %
 
-\textbf{Use version control.}  %
+\textbf{Use version control.} \cite{BaxterSusanM2006a, WilsonGreg2006a}  %
 Version control systems allow programmers to save a software package such that they can always
 return to that save point.  %
 All of the files in the package are saved together.  %
@@ -205,7 +224,7 @@ reason not to.  %
 If the language you are using has a convention for representing the version programmatically, such
 as a \python{__version__} attribute in Python, comply with that convention.  %
 
-\textbf{Test.} \cite{WilsonGreg2017a}  %
+\textbf{Test.} \cite{BaxterSusanM2006a, WilsonGreg2006a, WilsonGreg2017a}  %
 As the old saying goes, ``if it's not tested, it's broken''.  %
 If you rely on a piece of functionality in your software, consider writing a test that defines that
 functionality.  %
@@ -220,7 +239,7 @@ unless your project becomes very important.  %
 Distribute test datasets, when appropriate.  %
 Remember, your tests can serve double duty as simple minimal examples.  %
 
-\textbf{Collaborate and share.} \cite{WilsonGreg2017a, BarnesNick2010a}  %
+\textbf{Collaborate and share.} \cite{BaxterSusanM2006a, WilsonGreg2017a, BarnesNick2010a}  %
 If you are part of a team, consider sharing software and collaborating to create it.  %
 Try using practices like code review and issue tracking, but don't feel obligated to use them if it
 doesn't make sense for your project.  %
@@ -232,7 +251,10 @@ Put your software on an open platform, like GitHub \cite{GitHub}, and mint a DOI
 Cite your software, and ask other people who are using your software to do the same.  %
 Choose a license early, and choose permissive and commercially compatible unless you 1. know what
 you are doing and 2. plan to enforce.  %
-% TODO: cite 'publish your code it is good enough'
+Afraid to share because your code needs more polish?  %
+If your software is good enough to be used in active scientific research, it's worth sharing.  %
+As Nick Barnes says, \emph{``Publish your computer code: it is good enough''}.
+\cite{BarnesNick2010a}  %
 
 \textbf{Write human readable code, and document it well.} \cite{WilsonGreg2017a}  %
 Let the computer do the work, but write the program to be read by a human.  %
@@ -290,9 +312,9 @@ class Person():
 Now I can make some instances of that class, and access their attributes and methods.  %
 \begin{codefragment}{python}
 >>> mary = Person(name='Mary', favorite_food='pizza', hated_food='falafel')
->>> jane = Person(name='Jane', favorite_food='salad')
+>>> jane = Person(name='Jane', favorite_food='salad'')
 >>> mary.react_to('falafel')
-'gross---no thank you'''
+'gross---no thank you''''''
 >>> jane.react_to('salad')
 'yum! my favorite'
 >>> mary.favorite_food
-- 
cgit v1.2.3

