aboutsummaryrefslogtreecommitdiff
path: root/software
diff options
context:
space:
mode:
authorBlaise Thompson <blaise@untzag.com>2018-04-04 14:18:43 -0500
committerBlaise Thompson <blaise@untzag.com>2018-04-04 14:18:43 -0500
commitaff7629182048ea264a024fd32ceac70006a9caa (patch)
tree18e33698329ae30bc03abe70fdb5f4f436789bce /software
parentdc15adadcb2b7560d982c3aee0ef319b50d9d362 (diff)
2018-04-04 14:18
Diffstat (limited to 'software')
-rw-r--r--software/chapter.tex23
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} % ----------------------------------------------------------