add(sw dev1): var naming, comments

workshops/software_development/sections/documentation.tex

@@ -46,8 +46,33 @@
 \subsection{Comments}
 \label{sec:doc:comments}
 
-\begin{frame}{\insertsectionhead}
+\begin{frame}[fragile]{\insertsectionhead}
   \framesubtitle{\insertsubsectionhead}
+
+
+  \begin{itemize}
+    \item Add information directly to the code
+      \begin{itemize}
+        \item Explain usage, method, limits, references, justify decision, etc.
+      \end{itemize}
+    \item Comment blocks as function header 
+      \begin{itemize}
+        \item In Matlab, used for \lstmat{help} and \lstmat{lookfor}
+
+    \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.
+
+    \end{lstlisting}
+      \end{itemize}
+  \end{itemize}
 \end{frame}
 
 

workshops/software_development/sections/naming_conventions.tex

@@ -56,6 +56,17 @@
 \begin{frame}{\insertsectionhead}
   \framesubtitle{\insertsubsectionhead}
   Variables are in general in \lst{camelCase} or \lst{snake_case}.
+  \begin{itemize}
+    \item Longer name if large scope (used in all the code)
+    \item Shorter name for small scope (indices, iterators)
+    \item Avoid confusing names (\lst{point} and \lst{points} in the same code)
+    \item Prefix \lst{n} for number (\lst{nBlades}), \lst{i,j,k} for iterators (\lst{iFiles})
+    \item Avoid negative booleans: \lst{isConverged} better than
+      \lst{isNotConverged}
+    \item Avoid using 'special' names that would conflict with an built-in
+      function: \lst{mean}, \lst{cd}, \lst{sum}
+  \end{itemize}
+
 \end{frame}
 
 \subsection{Constants}