2018-04-04 14:18

1 files changed, 13 insertions, 10 deletions

diff --git a/software/chapter.tex b/software/chapter.tex
index 0027c5f..7fb9e6c 100644
--- a/software/chapter.tex
+++ b/software/chapter.tex
@@ -158,8 +158,8 @@ when properly applied.  %
 Before you sit down and implement a piece of software, stop!  %

 First you should try hard to find a library that already has what you need.  %

 You'll often surprise yourself with what you can find.  %

-Search the package repository for your language, such as PyPI [CITE], MATLAB File Exchange [CITE]

-or CRAN [CITE].  %

+Search the package repository for your language, such as PyPI \cite{PyPI}, MATLAB File Exchange

+\cite{FileExchange} or CRAN \cite{CRAN}.  %

 Even if there is not a full solution to your problem out there, there is almost certainly a

 solution to some part of it.  %

 Much better to have a dependency than a custom implementation.  %

@@ -177,8 +177,8 @@ As a general rule, once you have two classes you need multiple files.  %
 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.  %

-Consider conforming to specifications, such as Tidy Data. [CITE]  %

-If you must, use open binary formats such as HDF5.  %

+Consider conforming to specifications, such as Tidy Data \cite{WickhamHadley2014a}.  %

+If you must, use open binary formats such as HDF5 [CITE].  %

 Put as much metadata as you can into the file.  %

 Any piece of metadata that can automatically be added by the computer is essentially free---you

 might as well do it.  %

@@ -196,12 +196,13 @@ This is indispensable when trying to diagnose software problems.  %
 In order to use version control as effectively as possible, try to save the package after every

 change (feature addition, bugfix, etc).  %

 Typically version control is coupled with uploading to a remote server, for example using git with

-GitHub [CITE] or git.chem.wisc.edu [CITE], but version control need not be synonymous with

-uploading and distribution.  %

+GitHub \cite{GitHub} or git.chem.wisc.edu \cite{git.chem.wisc.edu}, but version control need not be

+synonymous with uploading and distribution.  %

 Tools like git have a lot of fantastic features beyond simply saving [CITE], but those are beyond the

 scope of these ``good enough'' recommendations.  %

 Also consider defining a version for the software package as a whole.  %

-Use semantic versioning [CITE], unless there is a strong reason not to.  %

+Use semantic versioning (MAJOR.MINOR.PATCH) \cite{SemanticVersioning}, unless there is a strong

+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.  %

 

@@ -245,9 +246,11 @@ Try to follow the recommended style for your language, but don't obsess about it
 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.  %

 Write first, and if it works, consider optimization.  %

-If you do need to make your software faster, use profiling tools like cProfile [CITE] and SnakeVis

-[CITE] to empirically determine what operations are taking the longest, rather than trying to guess

-or use intuition.  %

+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

+taking the longest, rather than trying to guess or use intuition.  %

+Only optimize speed-limiting operations, and stop optimizing once the code runs as quickly as

+needed.  %

 

 \section{Object oriented programming}  % ----------------------------------------------------------