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

fixed many index entries

Browse Source
This commit is contained in:
Jan Benda
2019-12-09 20:01:27 +01:00
parent f24c14e6f5
commit bf52536b7b
12 changed files with 332 additions and 306 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
codestyle/lecture/codestyle.tex
View File

@@ -1,4 +1,4 @@
\chapter{\tr{Code style}{Programmierstil}}
\chapter{Code style}
\shortquote{Any code of your own that you haven't looked at for six or
more months might as well have been written by someone
@@ -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-files}.
script is easily identified among the other \codeterm[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-files}
task (analysis) and to store all related \codeterm[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
@@ -307,8 +307,8 @@ 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-files} which
can be confusing. Sometimes such a code is called ``spaghetti
Not delegating the tasks leads to very long \codeterm[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,17 +323,17 @@ functions.
\end{important}
\subsection{Local and nested functions}
Generally, functions live in their own \codeterm{m-files} that have
the same name as the function itself. Delegating tasks to functions
thus leads to a large set of \codeterm{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 used within the
context of another function \matlab{} allows to define
\codeterm[function!local]{local functions} and
\codeterm[function!nested]{nested functions} within the same
file. Listing \ref{localfunctions} shows an example of a local
function definition.
Generally, functions live in their own \codeterm[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}
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
used within the context of another function \matlab{} allows to define
\entermde[function!local]{Funktion!lokale}{local functions} and
\entermde[function!nested]{Funktion!verschachtelte}{nested functions}
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}
@@ -408,11 +408,12 @@ advisable to adhere to these.
Repeated tasks should (to be read as must) be delegated to
functions. In cases in which a function is only locally applied and
not of more global interest across projects consider to define it as
\codeterm[function!local]{local function} or
\codeterm[function!nested]{nested function}. Taking care to increase
readability and comprehensibility pays off, even to the author!
\footnote{Reading tip: Robert C. Martin: \textit{Clean Code: A Handbook of
Agile Software Craftmanship}, Prentice Hall}
\entermde[function!local]{Funktion!lokale}{local function} or
\entermde[function!nested]{Funktion!verschachtelte}{nested
function}. Taking care to increase readability and comprehensibility
pays off, even to the author! \footnote{Reading tip: Robert
C. Martin: \textit{Clean Code: A Handbook of Agile Software
Craftmanship}, Prentice Hall}
\shortquote{Programs must be written for people to read, and only
incidentally for machines to execute.}{Abelson / Sussman}