From aff7629182048ea264a024fd32ceac70006a9caa Mon Sep 17 00:00:00 2001 From: Blaise Thompson Date: Wed, 4 Apr 2018 14:18:43 -0500 Subject: 2018-04-04 14:18 --- software/chapter.tex | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) (limited to 'software') 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} % ---------------------------------------------------------- -- cgit v1.2.3