add(sw dev1): details, examples and ccl

workshops/software_development/good_practices_slides.tex

@@ -200,46 +200,80 @@ sectionstyle=style2
 % Resources
 %\input{sections/resources.tex}
 
-% Bibliography
-\begin{frame}[allowframebreaks]{References}
-  \nocite{*} % Display all references regardless of if they were cited
-  \printbibliography[heading=none]
-\end{frame}
 
-
-%% =============================================================================
-%%                                 END
-%% =============================================================================
-
-\section*{Next session}
-\label{sec:next}
+\section{Conclusion}
+\label{sec:ccl}
 
 % ======================================
-\subsection{Contents (maybe)}
-\label{sec:next:contents}
+\subsection{Key take-away}
+\label{sec:ccl:takeaway}
 
 \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[\greencheck] Use meaningful names
       \begin{itemize}
-        \item Concept
-        \item \lst{git} in local
-        \item \lst{git} with a remote (Gitlab)
+        \item Different naming schemes for different elements
       \end{itemize}
-    \item Improve robustness through extensive testing
+    \pause
+    \item[\greencheck] \textbf{Use functions}
       \begin{itemize}
-        \item Unit testing
+        \item Don't repeat yourself
       \end{itemize}
-    \item Automation of tasks (tests, build, deployment)
+    \pause
+    \item[\greencheck] Document properly
       \begin{itemize}
-        \item Intro to CI/CD pipelines with Gitlab
+        \item Comment header for functions
+        \item In-line comments
+        \item (Readme if necessary)
       \end{itemize}
-  \end{enumerate}
+    \pause
+    \item[\greencheck] Good layout = easier to understand
+    \pause
+    \item[\greencheck] Add checks and early error detection
+  \end{itemize}
+\end{frame}
+
+% Bibliography
+\begin{frame}[allowframebreaks]{References}
+  \nocite{*} % Display all references regardless of if they were cited
+  \printbibliography[heading=none]
 \end{frame}
 
+
+%% =============================================================================
+%%                                 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/latexmkrc

@@ -11,4 +11,4 @@ $pdf_mode = 4;  # 1: use pdflatex, 4: use lualatex, 5 use xelatex
 $bibtex_use = 2;
 
 # Additional files to clean
-$clean_ext = 'synctex.gz synctex.gz(busy) run.xml tex.bak bcf fdb_latexmk run tdo %R-blx.bib nav snm'
+$clean_ext = 'synctex.gz synctex.gz(busy) run.xml tex.bak bcf fdb_latexmk run tdo %R-blx.bib nav snm vrb'

workshops/software_development/sections/documentation.tex

@@ -10,9 +10,10 @@
   \begin{itemize}
     \item Sadly, documentation is often overlooked
     \item Good practice: \textbf{documentation as you code}
+    \pause
     \item Ideal practice: Handbook-first
       \begin{itemize}
-        \item For \textit{big} projects
+        \item More suited for \textit{big} projects
         \item Clarifies the implementation and the structure of the code
         \item Speeds-up the development
         \item Ensures the documentation is written
@@ -25,20 +26,27 @@
         \item \alert{Code comments}, \lst{Readme} file, User/developer manual, Wiki, ...
       \end{itemize}
   \end{itemize}
-  \note[item]{See \textit{handbook-first} approach for interesting blog posts
-  and more details.}
-  \note[item]{Making the documentation transparent \textit{before} dissemination
-  of the code allows it to be treated as a \textit{single source of thrust}. All
+
+  \note[item]{The more a project grows, the more \textbf{vital} the
+  documentation becomes. At the same time, beginning the documentation of an
+  already established project is a massive and complicated task.}
+
+  \note[item]{For students projects and reports, documenting as you go is
+  probably the simplest and most efficient way to go.}
+
+  \note[item]{The handbook-first approach is particularity interesting for very
+  large codes, major projects (thesis) or big collaborative efforts. It allows
+  the documentation to be treated as a \textit{single source of thrust}. All
   contributors will look into the documentation to understand what the
-  software does and the reasons it was implemented that way.
-  No need to look into various chat apps, mails or to rely on our partial
-  understanding.}
+  software does and the reasons it was implemented that way. No need to look
+  into various chat apps, mails or to rely on our partial understanding. This
+  approach is however hard to implement properly, as it relies on all
+  developers to follow the rules.}
+
   \note[item]{An excellent documentation increases tremendously the efficiency
   on collaborative projects. It completely removes back-and-forth communication
   and misinterpretations based on poor code understanding.}
-  \note[item]{The more a project grows, the more \textbf{vital} the
-  documentation becomes. At the same time, beginning the documentation of an
-  already established project is a massive and complicated task.}
+
 \end{frame}
 
 \begin{frame}{\insertsectionhead}
@@ -78,12 +86,12 @@
       language=matlab,
       frame=single,
       ]
-function dyn_visc = viscosutherland(temp)
-% VISCOSUTHERLAND Sutherland's law for dynamic viscosity
+function dynVisc = visco_sutherland(temp)
+% VISCO_SUTHERLAND Sutherland's law for dynamic viscosity
 %   Determine the dynamic viscosity of ideal air 
 %   using only the temperatrue.
 %   Usage:
-%     mu = VISCOSUTHERLAND(temp)
+%     mu = VISCO_SUTHERLAND(temp)
 
       \end{lstlisting}
   \end{itemize}
@@ -108,8 +116,8 @@ function dyn_visc = viscosutherland(temp)
     frame=single,
     ]
 % Flip camberline, so the first element is the trailing edge
-xc = fliplr(coord(:, 1)); % [m]
-yc = fliplr(coord(:, 2)); % [m]
+camberX = fliplr(coord(:, 1)); % [m]
+camberY = fliplr(coord(:, 2)); % [m]
     \end{lstlisting}
     \pause
     \item Comments can also be used to separate clearly parts of the code (see
@@ -121,8 +129,11 @@ yc = fliplr(coord(:, 2)); % [m]
     frame=single,
     ]
 z = x + y % add y to x and put it in z
+thrust = 100; % thrust
     \end{lstlisting}
   \end{itemize}
+  \note[item]{Meaningful variable names are self-documenting.}
+
   \note[item]{Add units alongside the variables to avoid silly mistakes!\\
   \textit{On September 23, 1999 NASA lost the \$125 million Mars Climate Orbiter
   spacecraft after a 286-day journey to Mars. Miscalculations due to the use
@@ -148,14 +159,21 @@ z = x + y % add y to x and put it in z
     \item Add any relevant information (references, sources, links, etc.)
     \item Legal stuff (copyrights, etc.)
   \end{itemize}
+
+  \note[item]{When the \readme gets too long or too complicated, consider moving
+  to a "full" documentation (see next slides).}
+
   \note[item]{If your project is on Github, Gitlab, etc., the \readme is the
   front page of your project. The very first thing a new user will see. Keep
   that in mind!}
+
   \note[item]{The good practice is to use markdown (a very basic markup
   language) to format the \readme. This allows the website to format the page
   properly and display its content in a clear way.}
+
   \note[item]{If the \readme is to be read online, use images or badges to
   highlight the important features.}
+
   \note[item]{Examples:
     \begin{itemize}
       \item \url{https://gitlab.com/thlamb/beamertheme-trigon}
@@ -176,10 +194,12 @@ z = x + y % add y to x and put it in z
 
   \begin{frame}{\insertsectionhead}
     \framesubtitle{\insertsubsectionhead}
-    More suited for very big projects. Usually multiple pages pdf, or an online
-    wiki (or both).
+    More suited for \textit{very big} projects.
+      \begin{itemize}
+        \item Usually multiple pages pdf, or an online wiki (or both).
+      \end{itemize}
     \vfill
-
+    \pause
     \begin{columns}[T,onlytextwidth]
       \column{0.45\textwidth}
 

workshops/software_development/sections/errors.tex

@@ -21,7 +21,7 @@
 validateattributes(alpha, {'numeric'}, {'real', '2d', 'increasing'}, ...
                    mfilename(), 'alpha', 1);
 
-% Ensures that x is either 'string1' or 'string2'
+% Ensures that x is either 'student' or 'professor'
 x = validatestring(x, {'student','professor'}, mfilename()));
 \end{lstlisting}
   \end{itemize}
@@ -73,6 +73,7 @@ x = validatestring(x, {'student','professor'}, mfilename()));
         \item if $\mathcal{M} > 0.75$ the flow is no longer incompressible and
           the equations may be invalid
       \end{itemize}
+    \pause
     \item Write some simple functions that you call periodically in the code to
       detect issues early on
   \end{itemize}

workshops/software_development/sections/layout.tex

@@ -13,7 +13,7 @@
       \begin{itemize}
         \item \textbf{Never use TAB, always spaces!}
         \begin{itemize}
-          \item Standard is 4 spaces as indentation, 2 if you need conciseness
+          \item Standard is 4 spaces as indentation
           \item Tweak editor parameters to replace tabs by spaces
         \end{itemize}
         \item Sometime enforced by language (Python, etc.)
@@ -29,6 +29,8 @@
   \note[item]{Layout also involves deciding between double or single quotes
     (\lst{"}, \lst{'}).\\
   \faExclamationTriangle \, in \matlab they are different things!}
+  \note[item]{When codes are verbose or have many nested levels, indentations are
+  sometimes set to 2 spaces to keep the code concise.}
   \note[item]{You can also decide if you return to the line before opening a
   parenthesis, etc.}
 \end{frame}

workshops/software_development/sections/modularity.tex

@@ -106,6 +106,7 @@
         \item Separate file for functions shared across multiple
           functions/scripts
       \end{itemize}
+    \pause
     \item Main functions should have a good header comment, local functions
       should be self explanatory (one line description is enough)
     \item More abstraction = easier to reuse
@@ -181,3 +182,36 @@
   projects!
 \end{frame}
 
+
+% ======================================
+\subsection{Matlab packages}
+\label{sec:mod:matlab_package}
+
+\begin{frame}[fragile]{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  In \matlab, libraries are called \emph{packages}.
+  \begin{itemize}
+    \item identified by a \lst{+} before the directory name
+    \item must be explicitly imported in your script
+      \begin{lstlisting}[
+      language=matlab,
+      frame=single,
+      ]
+% Import all functions in the package
+import mypackage.*
+% Import a specific function in the package
+import mypackage.myfunction
+% Directly call the function without importing
+d = mypackage.myfunction(a,b,c);
+      \end{lstlisting}
+  \end{itemize}
+  \note[item]{Importing functions allow you to use them directly without
+  re-specifying the package name. In this case, it means you can use
+  myfunction(a,b,c) as if it were a normal function.}
+  \note[item]{The real advantage of package is that it ensures the functions
+  name are not conflicting with whatever function you have. If a package has a
+  function called \lst{plot_data} and your code happens to also have a different
+  \lst{plot_data}, you can easily pick which one to use without having to modify
+  the functions.}
+\end{frame}
+

workshops/software_development/sections/naming_conventions.tex

@@ -7,7 +7,7 @@
 \begin{frame}{\insertsectionhead}
   \framesubtitle{\insertsubsectionhead}
   List of rules to name and write the different elements (variables, functions,
-  constants, etc.) of the code.
+  files, etc.) of the code.
   \vfill
 
   Advantages:
@@ -28,11 +28,11 @@
   \framesubtitle{\insertsubsectionhead - Naming schemes}
   Common naming schemes are:
   \begin{itemize}
-    \item \lst{allsmallcaps} (also called flatcase)
-    \item \lst{ALLCAPS} (also called UPPERFLATCASE)
-    \item \lst{PascalCase}
+    \item \lst{flatcase}
     \item \lst{camelCase}
+    \item \lst{PascalCase}
     \item \lst{snake\_case}
+    \item \lst{UPPERFLATCASE}
     \item \lst{SCREAMING\_SNAKE\_CASE}
   \end{itemize}
 
@@ -71,7 +71,7 @@
 \subsection{Variables}
 \begin{frame}[fragile]{\insertsectionhead}
   \framesubtitle{\insertsubsectionhead}
-  Variables are in general in \lst{camelCase} or \lst{snake_case}.
+  Variables are in general in \lst{camelCase}
   \begin{itemize}
     \item Longer name if large scope (used in all the code)\\
     \item Shorter name for small scope (indices, iterators)\\
@@ -97,7 +97,7 @@ end
   \begin{itemize}
     \item Avoid confusing names (singular/plural of the same word)\\
       except if lists and arrays (special case): \lst{for point in points}
-    \item Prefix \lst{n} for number, \lst{i,j,k} for iterators\\
+    \item Prefix \lst{n} for number; \lst{i,j,k} for iterators\\
       \lst{nBlades}, \lst{nElements}, \lst{iFiles}, \lst{iSpeed}
     \item Avoid negative booleans (confusion when negating)
       \begin{itemize}
@@ -109,8 +109,8 @@ end
     \item Avoid using 'special' names that would conflict with an built-in
       functions
       \begin{itemize}
-        \item[\greencheck] \lst{myMean}, \lst{coeffDrag}, \lst{mySum}
         \item[\redcross] \lst{mean}, \lst{cd}, \lst{sum}
+        \item[\greencheck] \lst{myMean}, \lst{coeffDrag}, \lst{mySum}
       \end{itemize}
   \end{itemize}
 
@@ -137,7 +137,7 @@ end
     \begin{itemize}
       \item Should be clearly identified at the beginning of the script/function
       \item Should never be redefined later on in the code
-      \item Only think in \lst{SCREAMING_SNAKE_CASE}
+      \item Only thing in \lst{SCREAMING_SNAKE_CASE}
     \end{itemize}
 
     \column{0.4\textwidth}
@@ -196,8 +196,7 @@ DEFAULT_SOLVER = 'linear'
 \subsection{Functions}
 \begin{frame}[fragile]{\insertsectionhead}
   \framesubtitle{\insertsubsectionhead}
-  Functions are in general in \lst{allsmallcaps}, \lst{snake_case} or
-  \lst{camelCase}.
+  Functions are in general \lst{snake_case}.
   \vfill
   \begin{columns}[onlytextwidth]
     \column{0.55\textwidth}
@@ -215,13 +214,13 @@ DEFAULT_SOLVER = 'linear'
     language=python,
     frame=single,
   ]
-def calcdrag(aoa):
+def calc_drag(aoa):
     ...
 
-def plotpolar(aoa, coeff):
+def plot_polar(aoa, coeff):
     ...
 
-def mean(vect):
+def my_mean(vect):
     ...
 
     \end{lstlisting}

workshops/software_development/sections/organization.tex

@@ -39,18 +39,120 @@
 
 \begin{frame}{\insertsectionhead}
   \framesubtitle{\insertsubsectionhead - Matlab}
-  \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.
-  }
+    Typical project tree
+  \begin{columns}[onlytextwidth]
+    \column{0.4\textwidth}
+    \dirtree{%
+      .1 .
+      .2 data.
+      .2 doc.
+      .2 results.
+      .2 src.
+      .2 tests.
+      .2 LICENSE.
+      .2 Readme.md.
+      .2 \ldots.
+    }
+
+    \column{0.6\textwidth}
+    \begin{itemize}
+      \item \lst{src} folder is where the code is
+      \item \lst{doc} folder only for big projects
+      \item \lst{bin} folder if compiled binaries
+      \item \lst{scripts} folder if additional scripts
+    \end{itemize}
+  \end{columns}
+
+\end{frame}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead - Matlab}
+  \begin{columns}[onlytextwidth]
+    \column{0.45\textwidth}
+    \dirtree{%
+      .1 data.
+      .2 5deg.
+      .3 20220510-WT-10mps.csv.
+      .3 20220510-WT-20mps.csv.
+      .2 10deg.
+      .3 20220514-WT-10mps.csv.
+      .3 20220514-WT-20mps.csv.
+      .2 README.md.
+    }
+
+    \column{0.55\textwidth}
+    \begin{itemize}
+      \item Organize the data when many files
+      \item Add a small \readme in the folder
+        \begin{itemize}
+          \item Link source for the data
+          \item Explain how they are formatted
+          \item Explain what they mean
+          \item Detail how to read it
+        \end{itemize}
+    \end{itemize}
+  \end{columns}
+
 \end{frame}
 
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead - Matlab}
+  \begin{columns}[onlytextwidth]
+    \column{0.45\textwidth}
+    \dirtree{%
+      .1 src.
+      .2 main.m.
+      .2 analyze\_results.m.
+      .2 utils.
+      .3 calibrate\_sensors.m.
+      .3 clean\_wt\_data.m.
+      .3 remove\_peaks.m.
+      .2 libs.
+      .3 +af\_tools.
+      .3 +wt\_tools.
+    }
+
+    \column{0.55\textwidth}
+    \begin{itemize}
+      \item The files in the root of \lst{src} are the ones the user is supposed
+        to interact with
+      \item \lst{utils} is for small functions you wrote specifically for your
+        code
+      \item \lst{libs} is for general libraries\\
+        also called 'package' in \matlab
+    \end{itemize}
+  \end{columns}
+
+\end{frame}
+
+{
+  \setbeamertemplate{frame footer}{\advancedicon}
+  \begin{frame}{\insertsectionhead}
+    \framesubtitle{\insertsubsectionhead - Matlab}
+    \begin{columns}[onlytextwidth]
+      \column{0.45\textwidth}
+      \dirtree{%
+        .1 tests.
+        .2 utils.
+        .3 gen\_random\_data.m.
+        .2 test\_analyze\_results.m.
+        .2 test\_calibrate\_sensors.m.
+        .2 test\_clean\_wt\_data.m.
+        .2 test\_remove\_peaks.m.
+      }
+
+      \column{0.55\textwidth}
+      \begin{itemize}
+        \item In theory, each independent function should be accompanied by a
+          specific test function. That verifies its execution.
+        \item In the \lst{test} directory, \lst{utils} is for specific very
+          basic utilities used in the tests.
+        \item In \matlab, using \lstmat{runstests('tests')} will run all
+          functions starting with \lst{test\_} in the \lst{tests} directory.
+      \end{itemize}
+    \end{columns}
+
+  \end{frame}
+}
 % TODO: Add a Python example