add(workshop): soft dev 1

.gitlab-ci.yml

@@ -19,12 +19,15 @@ tex-compile:
   script:
     - git submodule init
     - git submodule update
+    # Probably a much better way to do all this!
     - cd APRI0004-ADP/BEMT
     - latexmk -pdf -f -interaction=nonstopmode *.tex
     - cd ../ADS
     - latexmk -pdf -f -interaction=nonstopmode *.tex
     - cd ../blown-wing
     - latexmk -pdf -f -interaction=nonstopmode *.tex
+    - cd ../../workshop/software_development
+    - latexmk -pdf -f -interaction=nonstopmode *.tex
   artifacts:
     name: "$CI_PROJECT_NAME-$CI_COMMIT_SHA"
     paths:

workshops/software_development/good_practices.tex

+% -----------------------------------------------------------------------------
+% This presentation is a small workshop whose goal is to introduce some
+% important good practices for software development. The goal is not to be
+% exhaustive, but simply help students make better codes easier to maintain.
+%
+% Author: Thomas Lambert <t.lambert@uliege.be>
+% ULiege - Aeroelasticity and Experimental Aerodynamics
+% MIT License
+% https://gitlab.uliege.be/thlamb/bemt
+% ------------------------------------------------------------------------------
+
+\documentclass[aspectratio=169]{beamer}
+
+\usetheme[
+titleformat=smallcaps,
+titlestyle=style2,
+headingcolor=theme,
+sectionstyle=style2
+]{trigon}
+
+\usepackage{ULiege-trigon}
+
+
+% ==============================================================================
+%                          MY PACKAGES AND CHANGES
+% ==============================================================================
+\usepackage{fontawesome5}
+\usepackage{booktabs}
+\newcommand\light[1]{\textcolor{ulgGrey}{#1}}
+
+% ==============================================================================
+%                          DOCUMENT METADATA
+% ==============================================================================
+\title{Software Development}
+\subtitle{I - Good practices}
+\author[TL]{Thomas Lambert}
+\date{\today}
+\titlegraphic{\includegraphics[height=\paperheight]{software.jpg}}
+
+
+
+%% =============================================================================
+%%                             BEGIN DOCUMENT
+%% =============================================================================
+\begin{document}
+
+% -------------------------------------
+% Title
+\titleframe
+
+
+% -------------------------------------
+% Introduction
+{
+  \AtBeginSection{} % Disables section frame here
+  \section*{Introduction}
+  \label{sec:intro}
+
+  % ======================================
+  \subsection{Objectives}
+  \begin{frame}{\insertsectionhead}
+    \framesubtitle{\insertsubsectionhead}
+    \begin{itemize}
+      \item I - Good practices
+        \begin{itemize}
+          \item Simplify maintenance/debugging
+          \item Improve readability and understanding
+          \item Improve robustness
+          \item Enhance team work
+          \item Save lot of time
+        \end{itemize}
+        \pause
+      \item \light{II - Advanced concepts}
+        \begin{itemize}
+          \item \light{Code quality metrics}
+          \item \light{Safer development with code versioning (git)}
+          \item \light{Improve robustness through extensive testing}
+          \item \light{Automation of tasks (tests, build, deployment)}
+        \end{itemize}
+    \end{itemize}
+  \end{frame}
+
+  % ======================================
+  \subsection{Disclaimer}
+  \begin{frame}{\insertsectionhead}
+    \framesubtitle{\insertsubsectionhead}
+    \begin{itemize}
+      \item This workshop aims to be as general as possible!
+        \begin{itemize}
+          \item Some specific advices may not apply in all cases
+          \item The idea is to put focus on important aspects and detail the
+            thought process
+          \item You should always check the good practices for the specific
+            language your are using
+          \item Emphasis will be put on Matlab and Python, but concepts apply to
+            all languages (including LaTeX, YAML, etc.)
+        \end{itemize}
+      \item Some examples are more a matter of preferences than hard truth. You
+        will always find someone to disagree with any of these points.
+        \begin{itemize}
+          \item \textbf{I am not a senior software developer}, I do not pretend
+            to be right on all these technical preferences.
+        \end{itemize}
+    \end{itemize}
+  \end{frame}
+
+
+% ======================================
+  \subsection{Contents}
+  \begin{frame}{\insertsectionhead}
+    \framesubtitle{\insertsubsectionhead}
+    \setcounter{tocdepth}{1}
+    \tableofcontents
+  \end{frame}
+}
+
+
+%% =============================================================================
+%%                              CONTENTS
+%% =============================================================================
+
+% Code style
+\input{sections/documentation.tex}
+\input{sections/naming_conventions.tex}
+\input{sections/layout.tex}
+
+% Software development
+\input{sections/modularity.tex}
+\input{sections/organization.tex}
+\input{sections/errors.tex}
+
+
+
+\end{document}

workshops/software_development/latexmkrc

+# LaTeXmk compiler configuration file
+# -----------------------------------------------------------------------------
+
+ensure_path('TEXINPUTS', '../../style//', '../../illustrations//');
+
+# Set compiler option (same option for all compilers)
+set_tex_cmds('-synctex=1 -interaction=nonstopmode -file-line-error %O %S');
+$pdf_mode = 4;  # 1: use pdflatex, 4: use lualatex, 5 use xelatex
+
+# Delete bbl files without checking if bib is available (dangerous when bib files are not available)
+$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'

workshops/software_development/sections/cicd.tex

+\section{Continuous Integration / Continuous Deployment (CI/CD)}
+\label{sec:cicd}
+
+\subsection{Introduction}
+
+
+

workshops/software_development/sections/documentation.tex

+\section{Documentation}
+\label{sec:doc}
+
+% ======================================
+\subsection{Introduction}
+\label{sec:doc:intro}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  \begin{itemize}
+    \pause
+    \item Sadly, documentation is often overlooked
+    \item The documentation of the code/software can have multiple forms
+      \begin{itemize}
+        \item \alert{Code comments}, Readme file, User/developer manual, Wiki, ...
+      \end{itemize}
+    \pause
+    \item Good practice: \textbf{documentation first}
+      \begin{itemize}
+        \item Clarifies the implementation and the structure of the code 
+        \item Speed-up the development
+        \item Ensures the documentation is written
+      \end{itemize}
+  \end{itemize}
+\end{frame}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  The role of the documentation is to
+  \begin{itemize}
+    \item Help the reader of the code understand how it is built and what it
+      does
+      \begin{itemize}
+        \item Ultra important if the reader is grading the code (projects,
+          thesis, etc)!
+        \item Important for teamwork on a same code
+        \item Important for future you that will debug/add feature
+      \end{itemize}
+    \item Explain the installation process, configuration, etc
+    \item Explain to the user how the code should be used (+ give examples)
+    \item Explain the limits of the code
+  \end{itemize}
+\end{frame}
+
+
+% ======================================
+\subsection{Comments}
+\label{sec:doc:comments}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+\end{frame}
+
+
+% ======================================
+\subsection{Readme}
+\label{sec:doc:readme}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  Add a small 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}
+\end{frame}
+
+
+% ======================================
+\subsection{Full documentation}
+\label{sec:doc:fulldoc}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  More suited for very big projects. Usually multiple pages pdf, or an online
+  wiki (or both).
+  \vfill
+
+  \begin{columns}[T,onlytextwidth]
+    \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}
+
+    \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}
+  \end{columns}
+\end{frame}
+
+
+
+% ======================================
+\subsection{Remark for graded codes (Academia)}
+\label{sec:doc:remark}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+
+  For projects, homework, exams, etc. the documentation:
+  \begin{itemize}
+    \item help prove that you did the work
+    \item shows understanding of the method
+    \item clarifies some assumptions and hypotheses made in the code
+    \item provides justification
+    \item helps teacher to understand the implementation and ensures fair
+      grades
+  \end{itemize}
+  \alert{There is no such thing as "too much information"!}
+
+\end{frame}

workshops/software_development/sections/errors.tex

+\section{Error handling}
+\label{sec:errors}
+

workshops/software_development/sections/git.tex

+\section{Version control}
+\label{sec:git}
+
+\subsection{Introduction}
+

workshops/software_development/sections/layout.tex

+\section{Code layout}
+\label{sec:layout}
+
+% ======================================
+\subsection{Concept}
+\label{sec:layout:concept}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  Following a good layout will improve readability tremendously.
+  \begin{itemize}
+    \item \alert{Proper indentation}
+      \begin{itemize}
+        \item Sometime enforced by language (Python, YAML, etc.)
+      \end{itemize}
+    \item Use white spaces to separate small code blocks
+    \item Use comments of separator lines to clearly separate elements
+    \item One line = one statement
+    \item Keep lines short (80-120 cols)
+  \end{itemize}
+\end{frame}
+
+
+% ======================================
+\subsection{Linters}
+\label{sec:layout:linters}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  Linters are software that automate and enforce code style.
+  \begin{itemize}
+    \item Ensure uniformity across all files
+    \item Ensure compliance to standard established (PEP 8, etc.)
+    \item Simplify version control (see II - Advanced concepts)
+  \end{itemize}
+  \vfill
+  \pause
+  They can be:
+  \begin{itemize}
+    \item Pre-implemented in IDEs (Matlab IDE, Pycharm, etc.)
+    \item Standalone tools (Matlab:
+      \href{https://florianschanda.github.io/miss_hit/}
+      {\color{ulgBlueGreenLight}{MISS\_HIT}}, Python:
+      \href{https://pypi.org/project/black/} {\color{ulgBlueGreenLight}{Black}},
+      etc.)
+    \item Plug-ins for your IDE (VSCode, Vim, emacs, etc.)
+  \end{itemize}
+\end{frame}

workshops/software_development/sections/libraries.tex

+\section{Libraries}
+\label{sec:lib}
+
+
+% ======================================
+\subsection{Introduction}
+\label{sec:lib:intro}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  Libraries are:
+  \begin{itemize}
+    \item a collection of programs and functions,
+    \item often related to a specific context,
+    \item that you can import and use without modification in your code.
+  \end{itemize}
+  \vfill
+  \pause
+  Advantages:
+  \begin{itemize}
+    \item Prevent re-implementing complex functions
+    \item Prevent copy/pasting the same stuff over and over again
+    \item Improve modularity even more
+  \end{itemize}
+\end{frame}
+
+
+% ======================================
+\subsection{Good practices}
+\label{sec:lib:goodpract}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  \alert{Avoid reinventing the wheel}
+  \begin{itemize}
+    \item Look for resources and open-source libraries to do the small tasks
+      %TODO: Matlab, python, matlab_airfoil_toolbox
+  \end{itemize}
+  If needed, build your own small libraries and import them in all your
+  projects!
+\end{frame}
+

workshops/software_development/sections/modularity.tex

+\section{Modularity}
+\label{sec:modularity}
+
+% ======================================
+\subsection{Introduction}
+\label{sec:mod:intro}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  \begin{itemize}
+    \item Modularity is \alert{the most important aspect} of proper software
+      development
+      \begin{itemize}
+        \item Consists in splitting a long code in multiple small functions
+      \end{itemize}
+  \end{itemize}
+  \vfill
+  \pause
+  Ideally, the functions should respect the following:
+  \begin{itemize}
+    \item Ideally no more than one task per function!
+    \item Limit number of input/output arguments (7-8 in total)
+    \item Limit number of lines (100 lines)
+    \item Limit number of nested loops (2-3 levels)
+    \item \textbf{DRY}: Don't Repeat Yourself!
+  \end{itemize}
+  \vfill
+  Any function that breaks that can likely be split in smaller, more manageable
+  functions.
+\end{frame}
+
+
+% ======================================
+\subsection{Advantages}
+\label{sec:mod:advantages}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+
+  \begin{itemize}
+    \item \textbf{Abstraction}
+      \begin{itemize}
+        \item No need to understand the inner working of each module
+        \item We can call functions from anywhere without bothering with the
+          details
+        \item Usage of a module is straightforward 
+      \end{itemize}
+      \pause
+    \item \textbf{Reusability}
+      \begin{itemize}
+        \item Each module can be reused in any other context
+        \item Prevent repeating yourself
+        \item \textit{Modules should be designed with that in mind}
+      \end{itemize}
+      \pause
+    \item \textbf{Improve clarity and readability}
+      \begin{itemize}
+        \item No superfluous details when reading the high-level function
+        \item Direct understanding of the code architecture
+      \end{itemize}
+  \end{itemize}
+
+\end{frame}
+
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead (2)}
+  \begin{itemize}
+    \item \textbf{Simplify maintenance and improve robustness}
+      \begin{itemize}
+        \item Changes in the function are applied everywhere     
+        \item Prevent issues when copy/pasting stuff
+        \item Enforce logical and cleaner code
+        \item Ensure consistency in inputs/outputs
+      \end{itemize}
+      \pause
+    \item \textbf{Simplify testing/debugging}
+      \begin{itemize}
+        \item Easier to test and debug small simple functions than large codes
+        \item Easy checks on function inputs/outputs
+        \item Possibility of automatic testing (\textit{unit testing})
+      \end{itemize}
+  \end{itemize}
+\end{frame}
+
+
+% ======================================
+\subsection{Remarks}
+\label{sec:mod:remarks}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  \begin{itemize}
+    \item You do not need to put every function in a separate file!
+      \begin{itemize}
+        \item Use local functions
+        \item Separate file for functions shared across multiple
+          functions/scripts
+      \end{itemize}
+    \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
+    \item Develop your own small libraries of very simple functions to reuse in
+      your projects
+  \end{itemize}
+\end{frame}
+
+
+% ======================================
+\subsection{Example}
+\label{sec:mod:example}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  BEMT project structure(?)
+\end{frame}
+
+
+
+% ======================================
+\subsection{Libraries}
+\label{sec:mod:lib}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  Libraries are:
+  \begin{itemize}
+    \item a collection of programs and functions,
+    \item often related to a specific context,
+    \item that you can import and use without modification in your code.
+  \end{itemize}
+  \vfill
+  \pause
+  Advantages:
+  \begin{itemize}
+    \item Prevent re-implementing complex functions
+    \item Prevent copy/pasting the same stuff over and over again
+    \item Improve modularity even more
+  \end{itemize}
+\end{frame}
+
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead (2)}
+  \alert{Avoid reinventing the wheel}
+  \begin{itemize}
+    \item Look for resources and open-source libraries to do the small tasks
+      %TODO: Matlab, python, matlab_airfoil_toolbox
+  \end{itemize}
+  If needed, build your own small libraries and import them in all your
+  projects!
+\end{frame}
+

workshops/software_development/sections/naming_conventions.tex

+\section{Naming conventions}
+\label{sec:naming}
+
+\subsection{Introduction}
+
+
+\subsection{Variables}
+
+\subsection{Constants}
+
+\subsection{Data structures}
+
+\subsection{Functions and classes}
+

workshops/software_development/sections/organization.tex

+\section{Project organization}
+\label{sec:orga}
+
+% ======================================
+\subsection{Introduction}
+\label{sec:orga:intro}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  A proper project organization clarifies the purposes of the different files.
+  \vfill
+  Good practice involve separating
+  \begin{itemize}
+    \item Source code
+    \item Compiled binaries
+    \item Libraries
+    \item Utilities
+    \item Documentation
+    \item Tests
+    \item Other files (Readme, License, git, examples)
+  \end{itemize}
+\end{frame}
+
+
+% ======================================
+\subsection{Example}
+\label{sec:orga:example}
+
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+
+
+\end{frame}

workshops/software_development/sections/testing.tex

+\section{Automatic testing}
+\label{sec:testing}
+