misc updates

programmingstyle/lecture/programmingstyle.tex

@@ -5,13 +5,14 @@
   else.}{Eagleson's law}
 
 %\selectlanguage{ngerman}
-Cultivating a good code style not a matter of good taste but is
-a key ingredient for understandability, maintainability and, in the end,
-facilitates reproducibility of scientific results. Programs should be
-written and structured in a way that supports outsiders as well the
-author himself --- a few weeks or months after it was written --- to
-understand the programs' rationale. Clean code pays off for the
-original author as well as others that are supposed to use the code.
+Cultivating a good code style is not just a matter of good taste but
+rather is a key ingredient for readability and maintainability of code
+and, in the end, facilitates reproducibility of scientific
+results. Programs should be written and structured in a way that
+supports outsiders as well the author himself --- a few weeks or
+months after it was written --- to understand the programs'
+rationale. Clean code pays off for the original author as well as
+others that are supposed to use the code.
 
 Clean code addresses several issues:
 \begin{enumerate}
@@ -35,7 +36,7 @@ of the program but two questions remain: (i) How to organize the files
 on the file system and (ii) how to name them that the controlling
 script is easily identified among the other \codeterm{m-files}.
 
-Upon installation ``MATLAB'' creates a folder called \emph{MATLAB} in
+Upon installation ``MATLAB'' creates a folder called \file{MATLAB} in
 the user space (Windows: My files, Linux: Documents, MacOS:
 Documents). Since this folder is already appended to the Matlab search
 path (Box~\ref{matlabpathbox}), it is easiest to stick to it for the
@@ -47,12 +48,12 @@ task (analysis) and to store all related \codeterm{m-files}
 (screenshot \ref{fileorganizationfig}). In these task-related folders
 one may consider to create a further sub-folder to store results
 (created figures, result data). On the project level a single script
-(analysis.m) controls the whole process. In parallel to the project
-folder we suggest to create an additional folder for functions that
-are or may be relevant across different projects.
+(\file{analysis.m}) controls the whole process. In parallel to the
+project folder we suggest to create an additional folder for functions
+that are or may be relevant across different projects.
 
 Within such a structure it is quite likely that programs in different
-projects share the same name (e.g. a ``load\_data.m''
+projects share the same name (e.g. a \varcode{load\_data.m}
 function). Usually this will not lead to conflicts due to the way
 matlab searches for matching functions which always starts in the
 current folder (more information on the \matlab-path in
@@ -63,7 +64,7 @@ Box~\ref{matlabpathbox}).
   \titlecaption{\label{fileorganizationfig} Possible folder structure
     for maintaining program code on the file system.}{For each project
     one maintains an individual folder in which analyses or tasks may
-    be structured in sub-folders. Within each analysis a ``main.m''
+    be structured in sub-folders. Within each analysis a \file{main.m}
     script is the entry point for the analyses. On the project level
     there could be a single script that triggers and controls all
     analyses and tasks in the sub-folders. Functions that are of
@@ -129,8 +130,8 @@ patterns:
 
 There are other common patterns such as the \emph{camelCase} in which
 the first character of compound words is capitalized. Other
-conventions use the underscore to separate the individual words (
-\emph{snake\_case}). A function that counts the number of action
+conventions use the underscore to separate the individual words
+(\emph{snake\_case}). A function that counts the number of action
 potentials could be named \file{spikeCount.m} or
 \file{spike\_count.m}.