add(sw dev1): draft naming convention

workshops/software_development/good_practices_slides.tex

@@ -17,13 +17,13 @@
   \documentclass[aspectratio=169]{beamer}
 \fi
 
+% Theme
 \usetheme[
   titleformat=smallcaps,
   titlestyle=style2,
   headingcolor=theme,
   sectionstyle=style2
 ]{trigon}
-
 \usepackage{ULiege-trigon}
 
 
@@ -34,6 +34,39 @@
 \usepackage{booktabs}
 \newcommand\light[1]{\textcolor{ulgGrey}{#1}}
 
+\usepackage{listings} %Typeset code exmaples
+\lstset{%
+  float=htbp,
+  basicstyle=\ttfamily\footnotesize,
+  keywordstyle=\color{ulgBlueGreen}\bfseries,
+  commentstyle=\color{ulgGrey}\itshape,
+  stringstyle=\color{ulgBlueGreenLight},
+  %backgroundcolor=\color{ulgBeigeLight!90},
+  numbers=none,
+  numberstyle=\tiny\ttfamily,
+  stepnumber=2,
+  showspaces=false,
+  showstringspaces=false,
+  showtabs=false,
+  frame=none,
+  framerule=0.5pt,
+  tabsize=2,
+  rulesep=5em,
+  captionpos=b,
+  breaklines=true,
+  breakatwhitespace=false,
+  framexleftmargin=0em,
+  framexrightmargin=0em,
+  xleftmargin=0em,
+  xrightmargin=0em,
+  aboveskip=1em,
+  belowskip=1em,
+}
+\newcommand\lst[1]{\lstinline[basicstyle=\ttfamily\normalsize]{#1}}
+\newcommand\lstmat[1]{\lstinline[language=matlab]{#1}}
+\newcommand\lstpy[1]{\lstinline[language=python]{#1}}
+
+\usepackage{dirtree} % Directory trees
 % ==============================================================================
 %                          DOCUMENT METADATA
 % ==============================================================================
@@ -44,18 +77,15 @@
 \titlegraphic{\includegraphics[height=\paperheight]{software.jpg}}
 
 
-
 %% =============================================================================
 %%                             BEGIN DOCUMENT
 %% =============================================================================
 \begin{document}
 
-% -------------------------------------
 % Title
 \titleframe
 
-
-% -------------------------------------
+% ======================================
 % Introduction
 {
   \AtBeginSection{} % Disables section frame here

workshops/software_development/sections/documentation.tex

@@ -8,19 +8,18 @@
 \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}
+    \pause
+    \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}
   \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

@@ -111,8 +111,24 @@
 \label{sec:mod:example}
 
 \begin{frame}{\insertsectionhead}
-  \framesubtitle{\insertsubsectionhead}
-  BEMT project structure(?)
+  \framesubtitle{\insertsubsectionhead -  BEMT Project}
+  \begin{table}
+    \begin{center}
+      \begin{tabular}[c]{ll}
+        \toprule
+        \lst{main} & Loads data, calls functions to solve Q1, Q2 and Q3\\
+        \lst{generatelem} & Generate geometric parameters for each element \\
+        \lst{bemt} & Output rotor perfs for a value of $\theta$ and $V_\infty$
+        \\
+        \lst{calcelem} & BEMT equations for a single element \\
+        \lst{plotrotorval} & Plots variables across the span \\
+        \lst{plotadvradio} & Plots metrics against advance ratio \\
+        \lst{...} & ... \\
+
+        \bottomrule
+      \end{tabular}
+    \end{center}
+  \end{table}
 \end{frame}
 
 

workshops/software_development/sections/naming_conventions.tex

@@ -2,13 +2,141 @@
 \label{sec:naming}
 
 \subsection{Introduction}
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  List of rules to name and write the different elements of the code.
+  \vfill
 
+  Advantages:
+  \begin{itemize}
+    \item Brings coherence
+    \item Helps the reviewer/maintainer to understand the code
+    \item Facilitate collaboration
+    \item Speed-up development
+    \item Reduce confusion
+    \item Requires less comments
+  \end{itemize}
+\end{frame}
+
+\subsection{Introduction}
+\begin{frame}{\insertsectionhead}
+  \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{camelCase}
+    \item \lst{snake\_case}
+    \item \lst{SCREAMING\_SNAKE\_CASE}
+    \item \lst{kebab-case}
+      \begin{itemize}
+        \item[\textcolor{ulgRed}{\faExclamationTriangle}] do not use in
+          engineering (confusion with 'minus' sign)
+      \end{itemize}
+  \end{itemize}
+\end{frame}
+
+\subsection{Generalities}
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  \begin{itemize}
+    \item The name of the elements should document their use\\
+      \lst{axialVel}, \lst{calcDrag}, \lst{AirfoilPolar}, \lst{reynolds}
+    \item Avoid too long names when possible\\
+      \lst{liftCoefficientSlope}, \lst{atmosphereDensityAtZeroAltitude}
+    \item Avoid too broad names\\
+      \lst{array}, \lst{finalResult}, \lst{var1}, \lst{var2}
+    \item Use prefix/suffix if it makes sense\\
+      \lst{vel_x}, \lst{vel_y}, \lst{temp_air}, \lst{temp_water}
+  \end{itemize}
+\end{frame}
 
 \subsection{Variables}
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  Variables are in general in \lst{camelCase} or \lst{snake_case}.
+\end{frame}
 
 \subsection{Constants}
+\begin{frame}[fragile]{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  Constants are in general in \lst{SCREAMING_SNAKE_CASE}.
+  \vfill
+
+  \begin{columns}[onlytextwidth]
+    \column{0.55\textwidth}
+
+    \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}
+    \end{itemize}
+
+    \column{0.4\textwidth}
+    \begin{lstlisting}[
+    language=python,
+    frame=single,
+  ]
+# Constants and defaults
+GRAVITY = 9.81
+COLOR_RED = '#FF0000'
+DEFAULT_SOLVER = 'linear'
+
+# Rest of the code
+...
+
+    \end{lstlisting}
+  \end{columns}
+
+\end{frame}
 
 \subsection{Data structures}
+\begin{frame}{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  Structures are in general in \lst{PascalCase}.
+
+  \begin{itemize}
+    \item Structure name is implicit, no need to repeat it in the fields
+      \begin{itemize}
+        \item[\textcolor{ulgGreen}{\faCheckCircle}] \lst{Segment.length}
+        \item[\textcolor{ulgRed}{\faTimesCircle}] \lst{Segment.segmentLength}
+      \end{itemize}
+  \end{itemize}
+\end{frame}
+
+\subsection{Functions}
+\begin{frame}[fragile]{\insertsectionhead}
+  \framesubtitle{\insertsubsectionhead}
+  Functions are in general in \lst{allsmallcaps}, \lst{snake_case} or
+  \lst{camelCase}.
+  \vfill
+  \begin{columns}[onlytextwidth]
+    \column{0.55\textwidth}
+
+    \begin{itemize}
+      \item Functions should be a verb
+      \item Use prefixes like \lst{get}, \lst{compute}, \lst{calculate},
+        \lst{find}, \lst{set},...
+      \item Use pairs for complement operation: \lst{create}/\lst{destroy} 
+      \item If one output, function name can be that output
+    \end{itemize}
+
+    \column{0.4\textwidth}
+    \begin{lstlisting}[
+    language=python,
+    frame=single,
+  ]
+def calcdrag(aoa):
+    ...
+
+def plotpolar(aoa, coeff):
+    ...
+
+def mean(vect):
+    ...
 
-\subsection{Functions and classes}
+    \end{lstlisting}
+  \end{columns}
+\end{frame}
 

workshops/software_development/sections/organization.tex

@@ -17,7 +17,7 @@
     \item Utilities
     \item Documentation
     \item Tests
-    \item Other files (Readme, License, git, examples)
+    \item Other files (Readme, License, git, linter configs, etc.)
   \end{itemize}
 \end{frame}
 
@@ -28,6 +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.
+}
 
 \end{frame}

workshops/software_development/sections/testing.tex

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