teaching/scientificComputing
Archived
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

removed \codeterm (replaced by \entermde)

Browse Source
This commit is contained in:
Jan Benda
2019-12-10 09:14:10 +01:00
parent c063cc9f0e
commit 39a1e51bc4
4 changed files with 100 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
codestyle/lecture/codestyle.tex
View File

@@ -33,7 +33,7 @@ by calling functions that work on the data and managing the
results. Applying this structure makes it easy to understand the flow
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-file]{m-files}.
script is easily identified among the other \entermde[m-file]{m-File}{m-files}.
Upon installation \matlab{} creates a folder called \file{MATLAB} in
the user space (Windows: My files, Linux: Documents, MacOS:
@@ -43,7 +43,7 @@ moment. Of course, any other location can specified as well. Generally
it is of great advantage to store related scripts and functions within
the same folder on the hard drive. An easy approach is to create a
project-specific folder structure that contains sub-folders for each
task (analysis) and to store all related \codeterm[m-file]{m-files}
task (analysis) and to store all related \entermde[m-file]{m-File}{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
@@ -73,18 +73,18 @@ Box~\ref{matlabpathbox}).
\begin{ibox}[tp]{\label{matlabpathbox}\matlab{} search path}
The \codeterm{search path} defines where \matlab{} looks for scripts
and functions. When calling a function from the command line
\matlab{} needs to figure out which function is addressed and starts
looking for it in the current path. If this fails it will crawl all
locations listed in the search path (see figure). The
\codeterm{search path} is basically a list of folders. \matlab{}
will go through this list from front to end and the search will stop
on the first match. This implies that the order in the search path
may affect which version of functions that share the same name is
used. Note: \matlab{} does not perform a recursive search. That is,
a function that resides in a sub-folder that is not explicitly
listed in the \codeterm{search path} will not be found.
The \entermde{Suchpfad}{search path} defines where \matlab{} looks
for scripts and functions. When calling a function from the command
line \matlab{} needs to figure out which function is addressed and
starts looking for it in the current path. If this fails it will
crawl all locations listed in the search path (see figure). The
\entermde{Suchpfad}{search path} is basically a list of
folders. \matlab{} will go through this list from front to end and
the search will stop on the first match. This implies that the order
in the search path may affect which version of functions that share
the same name is used. Note: \matlab{} does not perform a recursive
search. That is, a function that resides in a sub-folder that is not
explicitly listed in the \entermde{Suchpfad}{search path} will not be found.
\vspace{2ex}
\includegraphics[width=0.9\textwidth]{search_path}
@@ -307,7 +307,7 @@ and to briefly explain what they do. Whenever one feels tempted to do
this, one could also consider to delegate the respective task to a
function. In most cases this is preferable.
Not delegating the tasks leads to very long \codeterm[m-file]{m-files}
Not delegating the tasks leads to very long \entermde[m-file]{m-File}{m-files}
which can be confusing. Sometimes such a code is called ``spaghetti
code''. It is high time to think about delegation of tasks to
functions.
@@ -323,9 +323,9 @@ functions.
\end{important}
\subsection{Local and nested functions}
Generally, functions live in their own \codeterm[m-file]{m-files} that
Generally, functions live in their own \entermde[m-file]{m-File}{m-files} that
have the same name as the function itself. Delegating tasks to
functions thus leads to a large set of \codeterm[m-file]{m-files}
functions thus leads to a large set of \entermde[m-file]{m-File}{m-files}
which increases complexity and may lead to confusion. If the delegated
functionality is used in multiple instances, it is still advisable to
do so. On the other hand, when the delegated functionality is only
@@ -335,15 +335,17 @@ used within the context of another function \matlab{} allows to define
within the same file. Listing \ref{localfunctions} shows an example of
a local function definition.
\pagebreak[3] \lstinputlisting[label=localfunctions, caption={Example
for local functions.}]{calculateSines.m}
\pagebreak[3]
\lstinputlisting[label=localfunctions, caption={Example for local
functions.}]{calculateSines.m}
\emph{Local function} live in the same \codeterm{m-file} as the main
function and are only available in this context. Each local function
has its own \codeterm{scope}, that is, the local function can not
access (read or write) variables of the calling function. Interaction
with the local function requires to pass all required arguments and to
take care of the return values of the function.
\emph{Local function} live in the same \entermde{m-File}{m-file} as
the main function and are only available in this context. Each local
function has its own \enterm{scope}, that is, the local function can
not access (read or write) variables of the calling
function. Interaction with the local function requires to pass all
required arguments and to take care of the return values of the
function.
\emph{Nested functions} are different in this respect. They are
defined within the body of the parent function (between the keywords
@@ -356,13 +358,13 @@ should take care when defining nested functions.
\section{Specifics when using scripts}
A similar problem as with nested function arises when using scripts
(instead of functions). All variables that are defined within a script
become available in the global \codeterm{workspace}. There is the risk
of name conflicts, that is, a called sub-script redefines or uses the
same variable name and may \emph{silently} change its content. The
user will not be notified about this change and the calling script may
expect a completely different content. Bugs that are based on such
mistakes are hard to find since the program itself looks perfectly
fine.
become available in the global \enterm{workspace}
(\determ{Arbeitsbereich}). There is the risk of name conflicts, that
is, a called sub-script redefines or uses the same variable name and
may \emph{silently} change its content. The user will not be notified
about this change and the calling script may expect a completely
different content. Bugs that are based on such mistakes are hard to
find since the program itself looks perfectly fine.
To avoid such issues one should design scripts in a way that they
perform their tasks independent from other scripts and functions.