Skip to content
Snippets Groups Projects
Verified Commit 77a68ca5 authored by Thomas Lambert's avatar Thomas Lambert :helicopter:
Browse files

add,fix: implement Romain's comments

parent 589d4c01
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 171 additions and 131 deletions
workshops/software_development/good_practices_slides.tex
+ 19
− 13
View file @ 77a68ca5
......@@ -9,12 +9,15 @@
% https://gitlab.uliege.be/thlamb/bemt
% ------------------------------------------------------------------------------
% DEFINE THE PUBLIC (advanced has more details and nuances)
\def\advanced{1} % 1 or 0
% Automatically manage handout version
\ifdefined\ishandout
\documentclass[handout, notes, aspectratio=169]{beamer}
\usepackage[slide-frame=true, beamer-notes=true]{handoutWithNotes}
\pgfpagesuselayout{2 on 1 with notes landscape}[a4paper,border shrink=5mm]
\def\advanced{1}
\else
\documentclass[aspectratio=169]{beamer}
\fi
......@@ -74,10 +77,11 @@ sectionstyle=style2
\usepackage[maxnames=1, style=authoryear, date=year, isbn=false ]{biblatex}
\addbibresource{Workshop-SwDev1.bib}
\hypersetup{
urlcolor=ulgBlueGreenLight,
}
\newcommand{\fixedhref}[2]{\makebox[0pt][l]{\hspace*{\paperwidth}\href{#1}{#2}}\href{#1}{#2}}
\usepackage{menukeys}
\newcommand\greencheck{\textcolor{ulgGreen}{\faCheckCircle}}
\newcommand\redcross{\textcolor{ulgRed}{\faTimesCircle}}
\newcommand\advancedicon{\Large{\textcolor{ulgOrange}{\faSpaceShuttle}}}
% ==============================================================================
% DOCUMENT METADATA
% ==============================================================================
......@@ -115,6 +119,10 @@ sectionstyle=style2
Download these slides and the additional notes\\
\url{\repourl}
\end{columns}
\vfill
\pause
Advanced topics are indicated with a \advancedicon \, \normalsize on the
bottom left corner
\end{frame}
% ======================================
......@@ -154,14 +162,10 @@ sectionstyle=style2
\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.)
all languages (including LaTeX, C, C++, 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}
......@@ -181,14 +185,16 @@ sectionstyle=style2
%% CONTENTS
%% =============================================================================
% Setup work environment
\input{sections/organization.tex}
\input{sections/modularity.tex}
% Code style
\input{sections/documentation.tex}
\input{sections/naming_conventions.tex}
\input{sections/documentation.tex}
\input{sections/layout.tex}
% Software development
\input{sections/modularity.tex}
\input{sections/organization.tex}
% Errors
\input{sections/errors.tex}
% Resources
......
workshops/software_development/sections/documentation.tex
+ 73
− 67
View file @ 77a68ca5
......@@ -9,14 +9,18 @@
\framesubtitle{\insertsubsectionhead}
\begin{itemize}
\item Sadly, documentation is often overlooked
\item Good practice: \textbf{documentation first}
\item Good practice: \textbf{documentation as you code}
\item Ideal practice: Handbook-first
\begin{itemize}
\item 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
\end{itemize}
\pause
\item The documentation of the code/software can have multiple forms
\item The documentation starts with using \textbf{meaningful names} for the
elements
\item Multiple forms for doc:
\begin{itemize}
\item \alert{Code comments}, \lst{Readme} file, User/developer manual, Wiki, ...
\end{itemize}
......@@ -74,11 +78,12 @@
language=matlab,
frame=single,
]
function z = sum(x,y)
% 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.
function dyn_visc = viscosutherland(temp)
% VISCOSUTHERLAND Sutherland's law for dynamic viscosity
% Determine the dynamic viscosity of ideal air
% using only the temperatrue.
% Usage:
% mu = VISCOSUTHERLAND(temp)
\end{lstlisting}
\end{itemize}
......@@ -98,25 +103,25 @@ function z = sum(x,y)
\framesubtitle{\insertsubsectionhead}
\begin{itemize}
\item Use comments to explain a complex statement or give context
\begin{lstlisting}[
\begin{lstlisting}[
language=matlab,
frame=single,
]
]
% Flip camberline, so the first element is the trailing edge
xc = fliplr(coord(:, 1)); % [m]
yc = fliplr(coord(:, 2)); % [m]
\end{lstlisting}
\end{lstlisting}
\pause
\item Avoid obvious comments (surcharge code)
\begin{lstlisting}[
\item Comments can also be used to separate clearly parts of the code (see
\textit{Layout})
\pause
\item[\redcross] Avoid obvious comments (surcharge code)
\begin{lstlisting}[
language=matlab,
frame=single,
]
]
z = x + y % add y to x and put it in z
\end{lstlisting}
\pause
\item Comments can also be used to separate clearly parts of the code (see
\textit{Layout})
\end{lstlisting}
\end{itemize}
\note[item]{Add units alongside the variables to avoid silly mistakes!\\
\textit{On September 23, 1999 NASA lost the \$125 million Mars Climate Orbiter
......@@ -143,8 +148,6 @@ 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}
\pause
If it gets too long, needs for a dedicated "full" documentation.
\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!}
......@@ -166,58 +169,61 @@ z = x + y % add y to x and put it in z
% ======================================
\subsection{Full documentation}
\label{sec:doc:fulldoc}
{
\setbeamertemplate{frame footer}{\advancedicon}
\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{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}
\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}
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}
\note[item]{The wiki feature is pre-implemented on Github and Gitlab for that
purpose.}
\note[item]{Massive projects may benefit from a complete dedicated website
simplify even more the browsing of the documentation.
\begin{itemize}
\item \url{https://readthedocs.org}
\item \url{https://almanac.io}
\item \url{https://gohugo.io/}
\end{itemize}
}
\note[item]{Some languages have specific file types that can include the
documentation alongside the code. This is the case for Latex and the \lst{dux}
files. With that, the documentation is included in the code directly and files
are parsed with the latex interpreter to separate the documentation pdf and
the latex package code.
\begin{itemize}
\item Ex: \url{https://gitlab.com/thlamb/beamertheme-trigon}
\end{itemize}
}
\end{frame}
\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}
\note[item]{The wiki feature is pre-implemented on Github and Gitlab for that
purpose.}
\note[item]{Massive projects may benefit from a complete dedicated website
simplify even more the browsing of the documentation.
\begin{itemize}
\item \url{https://readthedocs.org}
\item \url{https://almanac.io}
\item \url{https://gohugo.io/}
\end{itemize}
}
\note[item]{Some languages have specific file types that can include the
documentation alongside the code. This is the case for Latex and the \lst{dux}
files. With that, the documentation is included in the code directly and files
are parsed with the latex interpreter to separate the documentation pdf and
the latex package code.
\begin{itemize}
\item Ex: \url{https://gitlab.com/thlamb/beamertheme-trigon}
\end{itemize}
}
\end{frame}
}
% ======================================
......
workshops/software_development/sections/errors.tex
+ 34
− 12
View file @ 77a68ca5
......@@ -6,33 +6,55 @@
\subsection{Defensive programming}
\label{sec:errors:def_prog}
\begin{frame}{\insertsectionhead}
\begin{frame}[fragile]{\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}
In \matlab \lstmat{validateattributes}, \lstmat{validatestring}
\begin{lstlisting}[
language=matlab,
frame=single,
basicstyle=\scriptsize,
]
% Ensures that 'alpha' is a 2D array of real increasing numbers.
validateattributes(alpha, {'numeric'}, {'real', '2d', 'increasing'}, ...
mfilename(), 'alpha', 1);
% Ensures that x is either 'string1' or 'string2'
x = validatestring(x, {'student','professor'}, mfilename()));
\end{lstlisting}
\end{itemize}
\note[item]{The extra options in \lstmat{validateattributes} allows to
perfectly tailor the error message. In this example, the error raised if alpha
violates the conditions will be:
\lst{Error using myfunction}\\
\lst{Expected input number 1, alpha, to be one of these types:}\\
\lst{double, single, ...}
}
\note[item]{By default, \lst{validatestring} is really forgiving on user
errors (this can be tailored). By reassigning its output to the variable, it
can correct a wrong user input to the expected one.\\
In this example, if we enter 'Student' or 'stud' or simply 's', the function
will recognize what we wanted and will store the proper expected value in
\lst{x}.
}
\end{frame}
\begin{frame}{\insertsectionhead}
\framesubtitle{\insertsubsectionhead}
When an issue is encountered, decide to
\begin{itemize}
\item Display \textit{meaningful} error message
\begin{itemize}
\item[\textcolor{ulgRed}{\faTimesCircle}] \lst{Error: function crashes!}
\item[\textcolor{ulgGreen}{\faCheckCircle}] \lst{Error in myFunction:}\\
\item[\redcross] \lst{Error: function crashes!}
\item[\greencheck] \lst{Error in myFunction:}\\
\lst{The value of X should be a positive scalar, found -2322343.}
\end{itemize}
\item Display warning and continue execution with a default value
\begin{itemize}
\item[\textcolor{ulgGreen}{\faCheckCircle}] \lst{Warning in myFunction:}\\
\item[\greencheck] \lst{Warning in myFunction:}\\
\lst{Mach = 0.85, flow may not be considered incompressible.}\\
\lst{Continuing execution, but expect erroneous results.}
\end{itemize}
......@@ -51,7 +73,7 @@
\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
\item Write some simple functions that you call periodically in the code to
detect issues early on
\end{itemize}
\end{frame}
......@@ -88,7 +110,7 @@
frame=single,
basicstyle=\scriptsize,
]
function checkMach(mach)
function checkmach(mach)
% CHECKMACH Checks if Mach is incompressible.
if mach > 0.75 && mach < 1
warning('myfunct:Transonic','Mach number is transonic (%f) !', mach);
......
workshops/software_development/sections/layout.tex
+ 11
− 7
View file @ 77a68ca5
......@@ -11,23 +11,24 @@
\begin{itemize}
\item \alert{Proper indentation}
\begin{itemize}
\item \textbf{Do not mix TAB and spaces!}
\item \textbf{Never use TAB, always spaces!}
\begin{itemize}
\item Standard is 4 spaces as indentation, 2 if you need conciseness
\item Tweak editor parameters to replace tab by spaces
\item Tweak editor parameters to replace tabs by spaces
\end{itemize}
\item Sometime enforced by language (Python, YAMS, etc.)
\item Sometime enforced by language (Python, etc.)
\end{itemize}
\item Use white spaces to separate small code blocks
\item Use blank lines 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}
\note[item]{As always \textbf{be consistent}!}
\note[item]{\matlab: Preferences > Editor > Tab}
\note[item]{\matlab smart indent: \keys{\ctrl + I} (or \keys{\cmd + I} on Mac)}
\note[item]{Layout also involves deciding between double or single quotes
(\lst{"}, \lst{'}).\\
\faExclamationTriangle in \matlab they are different things!}
\faExclamationTriangle \, in \matlab they are different things!}
\note[item]{You can also decide if you return to the line before opening a
parenthesis, etc.}
\end{frame}
......@@ -88,7 +89,9 @@ end
% ======================================
\subsection{Linters}
{
\setbeamertemplate{frame footer}{\advancedicon}
\subsection{Automatic formatting}
\label{sec:layout:linters}
\begin{frame}{\insertsectionhead}
......@@ -109,6 +112,7 @@ end
{\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.)
\item Plug-ins for your IDE (VSCode, etc.)
\end{itemize}
\end{frame}
}
workshops/software_development/sections/modularity.tex
+ 7
− 6
View file @ 77a68ca5
......@@ -11,14 +11,15 @@
\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
\item Consists in splitting a long code in multiple small functions and
libraries
\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 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 whenever possible (2-3 levels)
......@@ -48,17 +49,17 @@
\begin{itemize}
\item \textbf{Abstraction}
\begin{itemize}
\item No need to understand how each module works
\item No need to understand how each function works
\item We can call functions from anywhere without bothering with the
details
\item Usage of a module is straightforward
\item Usage of a function is straightforward
\end{itemize}
\pause
\item \textbf{Reusability}
\begin{itemize}
\item Each module can be reused in any other context
\item Each function can be reused in any other context
\item Prevent repeating yourself
\item \textit{Modules should be designed with that in mind}
\item \textit{Functions should be designed with that in mind}
\end{itemize}
\pause
\item \textbf{Improve clarity and readability}
......
workshops/software_development/sections/naming_conventions.tex
+ 21
− 22
View file @ 77a68ca5
......@@ -6,7 +6,8 @@
\subsection{Introduction}
\begin{frame}{\insertsectionhead}
\framesubtitle{\insertsubsectionhead}
List of rules to name and write the different elements of the code.
List of rules to name and write the different elements (variables, functions,
constants, etc.) of the code.
\vfill
Advantages:
......@@ -33,15 +34,15 @@
\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)\\
forbidden with many languages (\matlab, Python, C++, etc.)
\end{itemize}
\end{itemize}
\note[item]{Smart codes use different naming schemes for different elements of
the code. But once again, \textbf{be consistent}.}
\pause
\alert{Use different schemes for different elements} and then \textbf{be
consistent}.
\note[item]{There is also the \lst{kebab-case}, but this is usually forbidden
in many 'non-web' languages as the \lst{-} could be misinterpreted with the
'minus' sign.}
\end{frame}
......@@ -79,9 +80,9 @@
frame=single,
]
drag = 10;
airspeed = 40:200;
airSpeed = 40:200;
for i = 1:length(airspeed)
for i = 1:length(airSpeed)
...
end
\end{lstlisting}
......@@ -95,23 +96,21 @@ end
\framesubtitle{\insertsubsectionhead (2)}
\begin{itemize}
\item Avoid confusing names (singular/plural of the same word)\\
except if iteration (special case): \lst{for point in points}
except if lists and arrays (special case): \lst{for point in points}
\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}
\item[\textcolor{ulgGreen}{\faCheckCircle}] \lst{isConverged}
\item[\greencheck] \lst{isConverged}
$\rightarrow$ \lst{not(isConverged)}
\item[\textcolor{ulgRed}{\faTimesCircle}] \lst{isNotConverged}
\item[\redcross] \lst{isNotConverged}
$\rightarrow$ \lst{not(isNotConverged)}
\end{itemize}
\item Avoid using 'special' names that would conflict with an built-in
functions
\begin{itemize}
\item[\textcolor{ulgRed}{\faTimesCircle}] \lst{mean}, \lst{coeffDrag},
\lst{mySum}
\item[\textcolor{ulgGreen}{\faCheckCircle}] \lst{mean}, \lst{cd},
\lst{sum}
\item[\greencheck] \lst{myMean}, \lst{coeffDrag}, \lst{mySum}
\item[\redcross] \lst{mean}, \lst{cd}, \lst{sum}
\end{itemize}
\end{itemize}
......@@ -129,7 +128,7 @@ end
\subsection{Constants}
\begin{frame}[fragile]{\insertsectionhead}
\framesubtitle{\insertsubsectionhead}
Constants are in general in \lst{SCREAMING_SNAKE_CASE}.
Constants must be in \lst{SCREAMING_SNAKE_CASE}.
\vfill
\begin{columns}[onlytextwidth]
......@@ -175,7 +174,7 @@ DEFAULT_SOLVER = 'linear'
% ======================================
\subsection{Data structures}
\subsection{Data structures (\matlab)}
\begin{frame}{\insertsectionhead}
\framesubtitle{\insertsubsectionhead}
Structures are in general in \lst{PascalCase}.
......@@ -183,8 +182,8 @@ DEFAULT_SOLVER = 'linear'
\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}
\item[\greencheck] \lst{Segment.length}
\item[\redcross] \lst{Segment.segmentLength}
\end{itemize}
\item Field names should follow nomenclature used for variables.
......
workshops/software_development/sections/organization.tex
+ 6
− 4
View file @ 77a68ca5
......@@ -8,6 +8,7 @@
\begin{frame}{\insertsectionhead}
\framesubtitle{\insertsubsectionhead}
A proper project organization clarifies the purposes of the different files.
\vfill
Good practice involve separating
......@@ -15,7 +16,7 @@
\column{0.5\textwidth}
\begin{itemize}
\item Source code
\item Compiled binaries
\item Documentation
\item Libraries
\item Utilities
\item Other files (\readme, License, etc.)
......@@ -23,10 +24,10 @@
\column{0.5\textwidth}
\begin{itemize}
\item Documentation
\item Tests
\item Data
\item Results
\item Compiled binaries
\end{itemize}
\end{columns}
\end{frame}
......@@ -37,7 +38,7 @@
\label{sec:orga:example}
\begin{frame}{\insertsectionhead}
\framesubtitle{\insertsubsectionhead}
\framesubtitle{\insertsubsectionhead - Matlab}
\dirtree{%
.1 .
.2 src.
......@@ -50,5 +51,6 @@
.2 tests.
.2 README.md.
}
\end{frame}
% TODO: Add a Python example
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment