add(sw dev1): errors handling

workshops/software_development/good_practices_slides.tex

@@ -12,17 +12,17 @@
 
 % Automatically manage handout version
 \ifdefined\ishandout
-  \documentclass[handout, aspectratio=169]{beamer}
+\documentclass[handout, aspectratio=169]{beamer}
 \else
-  \documentclass[aspectratio=169]{beamer}
+\documentclass[aspectratio=169]{beamer}
 \fi
 
 % Theme
 \usetheme[
-  titleformat=smallcaps,
-  titlestyle=style2,
-  headingcolor=theme,
-  sectionstyle=style2
+titleformat=smallcaps,
+titlestyle=style2,
+headingcolor=theme,
+sectionstyle=style2
 ]{trigon}
 \usepackage{ULiege-trigon}
 
@@ -141,7 +141,7 @@
   \end{frame}
 
 
-% ======================================
+  % ======================================
   \subsection{Contents}
   \begin{frame}{\insertsectionhead}
     \framesubtitle{\insertsubsectionhead}
@@ -166,5 +166,41 @@
 \input{sections/errors.tex}
 
 
+%% =============================================================================
+%%                                 END
+%% =============================================================================
+
+\section*{Next session}
+\label{sec:next}
+
+
+% ======================================
+\subsection{Contents (maybe)}
+\label{sec:next:contents}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  \begin{enumerate}
+    \item Code quality metrics
+      \begin{itemize}
+        \item Nesting levels, cyclomatic complexity, function paths, etc.
+      \end{itemize}
+    \item Code versioning (\lst{git})
+      \begin{itemize}
+        \item Concept
+        \item \lst{git} in local
+        \item \lst{git} with a remote (Gitlab)
+      \end{itemize}
+    \item Improve robustness through extensive testing
+      \begin{itemize}
+        \item Unit testing
+      \end{itemize}
+    \item Automation of tasks (tests, build, deployment)
+      \begin{itemize}
+        \item Intro to CI/CD pipelines with Gitlab
+      \end{itemize}
+  \end{enumerate}
+\end{frame}
+
 
 \end{document}

workshops/software_development/sections/documentation.tex

@@ -11,14 +11,14 @@
     \item Sadly, documentation is often overlooked
     \item Good practice: \textbf{documentation first}
       \begin{itemize}
-        \item Clarifies the implementation and the structure of the code 
+        \item Clarifies the implementation and the structure of the code
         \item Speed-up the development
         \item Ensures the documentation is written
       \end{itemize}
-    \pause
+      \pause
     \item The documentation of the code/software can have multiple forms
       \begin{itemize}
-        \item \alert{Code comments}, Readme file, User/developer manual, Wiki, ...
+        \item \alert{Code comments}, \lst{Readme} file, User/developer manual, Wiki, ...
       \end{itemize}
   \end{itemize}
 \end{frame}
@@ -55,22 +55,21 @@
       \begin{itemize}
         \item Explain usage, method, limits, references, justify decision, etc.
       \end{itemize}
-    \item Comment blocks as function header 
+    \item Comment blocks as function header
       \begin{itemize}
         \item In Matlab, used for \lstmat{help} and \lstmat{lookfor}
 
-    \begin{lstlisting}[
+          \begin{lstlisting}[
     language=matlab,
     frame=single,
   ]
 function z = sum(x,y)
-    % SUM  Returns the sum of the two inputs
-    %   This function returns the sum of the two input numbers.
-    %   Usage:
-    %     z = SUM(x,y), returns z, the sum of x and y, 
-    %     where both x and y are scalars.
+          % SUM  Returns the sum of the two inputs
+          %   Usage:
+          %     z = SUM(x,y), returns z, the sum of x and y,
+          %     where both x and y are scalars.
 
-    \end{lstlisting}
+          \end{lstlisting}
       \end{itemize}
   \end{itemize}
 \end{frame}
@@ -82,18 +81,18 @@ function z = sum(x,y)
 
 \begin{frame}{\insertsectionhead}
   \framesubtitle{\insertsubsectionhead}
-  Add a small Readme file (\textit{.txt} or \textit{.md}) at the root of the
+  Add a small \lst{README} file (\textit{.txt} or \textit{.md}) at the root of the
   directory.
 
   Purpose:
-      \begin{itemize}
-        \item Explain purpose of the code
-        \item Explain installation and configuration
-        \item List dependencies
-        \item List major functions and how they should be used
-        \item Add any relevant information (references, sources, links, etc.)
-        \item Legal stuff (copyrights, etc.)
-      \end{itemize}
+  \begin{itemize}
+    \item Explain purpose of the code
+    \item Explain installation and configuration
+    \item List dependencies
+    \item List major functions and how they should be used
+    \item Add any relevant information (references, sources, links, etc.)
+    \item Legal stuff (copyrights, etc.)
+  \end{itemize}
 \end{frame}
 
 
@@ -111,24 +110,24 @@ function z = sum(x,y)
     \column{0.45\textwidth}
 
     User manual
-      \begin{itemize}
-        \item Installation and configuration
-        \item Usage (details on every single functions)
-        \item Limits of the software
-        \item Errors troubleshooting
-        \item ...
-      \end{itemize}
+    \begin{itemize}
+      \item Installation and configuration
+      \item Usage (details on every single functions)
+      \item Limits of the software
+      \item Errors troubleshooting
+      \item ...
+    \end{itemize}
 
     \column{0.45\textwidth}
     \pause
     Developer manual
-      \begin{itemize}
-        \item Code architecture
-        \item Coding style
-        \item Implementation choices
-        \item Dependencies
-        \item Known issues
-      \end{itemize}
+    \begin{itemize}
+      \item Code architecture
+      \item Coding style
+      \item Implementation choices
+      \item Dependencies
+      \item Known issues
+    \end{itemize}
   \end{columns}
 \end{frame}
 

workshops/software_development/sections/errors.tex

 \section{Error handling}
 \label{sec:errors}
 
+
+% ======================================
+\subsection{Defensive programming}
+\label{sec:errors:def_prog}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  The art of thinking about all the possible \alert{wrong} ways to use the code.
+  \begin{itemize}
+    \item Check user inputs (type, size, value, etc)\\
+      In Matlab: \lstmat{validateattributes}, \lstmat{validateattributes}
+    \item Add small tests in the scripts and functions
+      \begin{itemize}
+        \item check if values are within expected ranges
+        \item check if violate method hypothesis
+      \end{itemize}
+  \end{itemize}
+
+  When an issue is encountered, decided to
+  \begin{itemize}
+    \item Display \textit{meaningful} error message
+    \item Display warning and continue execution with a default value
+  \end{itemize}
+\end{frame}
+
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  Early error detection can save you lots of time for the debugging
+  \begin{itemize}
+    \item Especially easy for codes based on physical quantities
+      \begin{itemize}
+        \item a distance or a consumption can not be negative
+        \item a temperature of 50,000 K in an engine is unlikely
+        \item if $\mathcal{M} > 0.75$ the flow is no longer incompressible and
+          the equations may be invalid
+      \end{itemize}
+    \item Write some simple functions that you cal periodically in the code to
+      detect issues early on
+  \end{itemize}
+\end{frame}
+
+% ======================================
+\subsection{Error display}
+\label{sec:errors:display}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  Do not hesitate to display properly crafted output messages
+  \begin{enumerate}
+    \item \lst{print}: Non-critical
+      \begin{itemize}
+        \item information messages, results, etc.
+      \end{itemize}
+    \item \lst{warning}: Concerning but not critical.\\
+      Lets the program continue, but user should be careful to the results.
+      \begin{itemize}
+        \item violation of hypothesis, default value selected because wrong
+          input, etc
+      \end{itemize}
+    \item \lst{error}: Critical issue.\\
+      Stop the execution of the program completely.
+  \end{enumerate}
+\end{frame}
+
+
+\begin{frame}[fragile]{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  Printing such messages is really simple with Matlab
+  \begin{lstlisting}[
+    language=matlab,
+    frame=single,
+    basicstyle=\scriptsize,
+  ]
+function checkMach(mach)
+  % CHECKMACH Checks if Mach is incompressible.
+  if mach > 0.75 && mach < 1
+    warning('myfunct:Transonic','Mach number is transonic (%f) !', mach);
+  elseif Mach >= 1
+    error('myfunct:Supersonic','Mach number is supersonic (%f) !', mach);
+  end
+end
+\end{lstlisting}
+
+\begin{itemize}
+  \item Use comprehensive error code and message!
+\end{itemize}
+
+\end{frame}

workshops/software_development/sections/layout.tex

@@ -21,6 +21,55 @@
 \end{frame}
 
 
+% ======================================
+\subsection{Example}
+\label{sec:layout:example}
+
+\begin{frame}[fragile]{\insertsectionhead}
+  %\framesubtitle{\insertsubsectionhead}
+  \begin{columns}[T,onlytextwidth]
+    \column{0.48\textwidth}
+    \begin{lstlisting}[
+    language=matlab,
+    frame=single,
+    basicstyle=\scriptsize,
+  ]
+c_l=0.100*aoa+.5;
+c_d=0.120*aoa^2-0.001*aoa;
+x=linspace(0,100,100);y=x.^2;
+function out = myfucnt(a,b,c)
+if a == true
+out=b+c;
+else
+out=a;
+end
+  end
+    \end{lstlisting}
+
+    \column{0.48\textwidth}
+    \begin{lstlisting}[
+    language=matlab,
+    frame=single,
+    basicstyle=\scriptsize,
+  ]
+c_l = 0.100 * aoa + 0.5;
+c_d = 0.120 * aoa^2 - 0.001 * aoa;
+x = linspace(0,100,100);
+y = x.^2;
+
+    % -----------------------
+function out = myfucnt(a, b, c)
+  if a == true
+    out = b + c;
+  else
+    out = a;
+  end
+end
+    \end{lstlisting}
+  \end{columns}
+\end{frame}
+
+
 % ======================================
 \subsection{Linters}
 \label{sec:layout:linters}

workshops/software_development/sections/organization.tex

@@ -28,17 +28,17 @@
 
 \begin{frame}{\insertsectionhead}
   \framesubtitle{\insertsubsectionhead}
-\dirtree{%
-.1 .
-.2 src.
-.3 main.m.
-.3 utils.
-.4 plotresult.m.
-.4 sanitizeinput.m.
-.3 lib.
-.4 +af\_tools.
-.2 tests.
-.2 README.md.
-}
+  \dirtree{%
+    .1 .
+    .2 src.
+    .3 main.m.
+    .3 utils.
+    .4 plotresult.m.
+    .4 sanitizeinput.m.
+    .3 lib.
+    .4 +af\_tools.
+    .2 tests.
+    .2 README.md.
+  }
 
 \end{frame}