From 92b0eaa59ac85b9fa7b4bbb61ce84949e96e286b Mon Sep 17 00:00:00 2001
From: Blaise Thompson <blaise@untzag.com>
Date: Fri, 13 Apr 2018 22:39:33 -0500
Subject: 2018-04-13 22:39

---
 software/chapter.tex | 29 +++++++++--------------------
 1 file changed, 9 insertions(+), 20 deletions(-)

(limited to 'software/chapter.tex')

diff --git a/software/chapter.tex b/software/chapter.tex
index e6707dd..06fcff9 100644
--- a/software/chapter.tex
+++ b/software/chapter.tex
@@ -1,14 +1,3 @@
-%A whole set of licenses have been written to use for this purpose.  %
-%Briefly, strong copyleft licenses do not allow for software to be modified or enhancements without
-%sharing those enhancements under the same licenses.  %
-%These ``viral'' licenses are meant to force companies and individuals who would otherwise not open
-%source to share their code.  %
-%The strongest copyleft licenses do not even allow others to link against the licensed software
-%without themselves being copyleft.  %
-%This strategy has been moderately successful, but is becoming less popular.  % TODO: cite
-%Open source licenses are less opinionated, merely granting users the right to copy, modify,
-%distribute, and publish code without restriction except perhaps credit to the source.  %
-
 \chapter{Software} \label{cha:sof}
 
 \begin{dquote}
@@ -117,24 +106,22 @@ Other funding agencies have similar projects.  %
 
 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.  %
+those that I have found most relevant.  %
 
 \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.  %
+amount of domain-specific knowledge that only ``end-users'' possess.  %
 Software development practices may not be valued in a scientific environment.  %
 End-users may lack the skill and knowledge required to develop high quality, maintainable
 software.  %
 They may not be aware of best practices in software development.  %
 They focus on feature additions and neglect documentation and maintenance.  %
-% BJT: what are the consequences of end-users
-
 
 \textbf{Shifting goals.} \cite{SegalJudith2005a, CarverJeffreyC2007a, HannayJoErskine2009a,
   PrabhuPrakash2011a}
-Many traditional software development paradigms demand an upfront articulation of goals and
+Traditional software development paradigms typically 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
 written.  %
@@ -181,8 +168,8 @@ loop of critical self assessment that science depends upon.  %
 On the positive side, testing can be an easy-to-add development practice with huge rewards.  %
 Well written tests can be a programmers best friend: helping her to ensure that her code has met
 all of the given requirements.  %
-Well written tests allow programmers to optimize without worrying about breaking crucial components
-of their software.  %
+This allows programmers to optimize without worrying about breaking crucial components of their
+software.  %
 
 \textbf{Struggles with optimization.} \cite{PrabhuPrakash2011a}
 Sometimes, a scientific application requires performant code.  %
@@ -219,7 +206,7 @@ Make your dependencies explicit, in machine readable ways where possible.  %
 \textbf{Do not duplicate.} \cite{WilsonGreg2017a}  %
 If you do need to write some software, make sure that you do not duplicate code within your own
 work.  %
-Instead of writing the same 10 lines of code again and again with small tweaks, write a function
+Instead of writing the same few lines of code again and again with small tweaks, write a function
 that accepts a set of arguments.  %
 If you are doing the same operation in many different contexts, consider defining a library to that
 operation that can be imported and shared between your different projects.  %
@@ -292,7 +279,7 @@ 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.  %
+Let the computer do the work, but write the source code to be read by a human.  %
 Give classes, functions, attributes and variables meaningful names.  %
 Don't be afraid to be verbose, most programming environments have tab completion so long names are
 not all that hard to type.  %
@@ -301,6 +288,8 @@ Try to follow the recommended style for your language, but don't obsess about it
 \textbf{Avoid premature optimization.} \cite{WilsonGreg2014a, WilsonGreg2017a}
 Don't get pulled into the trap of trying to make things perfect the first time.  %
 Software design is typically a very iterative process, and for good reason.  %
+This is particularly true in a scientific context, where goals may evolve during the development
+process.  %
 Write for correctness first, and if it works, consider optimization.  %
 If you do need to make your software faster, use profiling tools like cProfile
 \cite{PythonProfilers} and SnakeViz \cite{SnakeViz} to empirically determine what operations are
-- 
cgit v1.2.3

