2018-04-13 22:39

1 files changed, 9 insertions, 20 deletions

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