From: Jan Michel <j.michel@gsi.de>
Date: Thu, 16 Nov 2017 10:13:12 +0000 (+0100)
Subject: add some coding style
X-Git-Url: https://jspc29.x-matter.uni-frankfurt.de/git/?a=commitdiff_plain;h=f811aa12d0e28bee39da2b9155739d3dc355e10a;p=daqdocu.git

add some coding style
---

diff --git a/trb3/CodeRepository.tex b/trb3/CodeRepository.tex
index 20f2fe3..664818f 100644
--- a/trb3/CodeRepository.tex
+++ b/trb3/CodeRepository.tex
@@ -77,6 +77,44 @@ tutorial here (this can be googled duckduckgo'ed).
  \item Developers upload their files via scp to \\\verb!hadaq@jspc29.x-matter.uni-frankfurt.de:/srv/www/htdocs/bitfiles/!
 \end{itemize*}
 
+
+\subsection{Coding Style}
+There is no mandatory coding style, but most code follows these simple rules to make it easier to read by others:
+\begin{itemize*}
+\item Indentation is done using two spaces per level. If tabs are used, make sure the width is set to two.
+\item Keywords (if, process, case) are written in lower case.
+\item variable and signal names are lower case. Use prefixes (\verb!buf\_!, \verb!next\_!, \verb!reg\_!) and suffixes (\verb!\_i! for internal signals, \verb!\_q! after a FF) and keep the base name the same if necessary. 
+\item Inputs and outputs should be identifiable. Use \verb!\_OUT! and \verb!\_IN! as suffix, or use a very obvious naming.
+\item All blocks are named using capital letters. Use a common prefixing: \verb!PROC\_XYZ! for processes, \verb!GEN\_! for generate, \verb!THE\_! for instances.
+\item Use speaking names, keep them precise but not too long. Use a common namespace for signals that belong to the same logical group.
+\item Each section of the code should get a title like
+  \begin{verbatim}
+-----------------------------------------------------------------
+-- DescribeMe
+----------------------------------------------------------------- 
+\end{verbatim}
+\item For synchronous processes, use the handy 'wait until' syntax which avoids one level of 'if', the possibility of asynchronous resets and all trouble with sensitivity lists:
+  \begin{verbatim}
+  PROC_DO : process begin
+  wait until rising_edge(CLK);
+  [...]
+\end{verbatim}
+\item Do not put component declarations into the archticture. Either have a separated package file with all components, or use \verb!THE_ID : entity work.ENTITYNAME! syntax.
+\item Use indentation and alignment also within the code line, e.g. here are all signal names aligned and easier to read:
+  \begin{verbatim}
+THE_MAIN_PLL : pll_in200_out100
+  port map (
+    CLK    => CLK_GPLL_LEFT,
+    RESET  => '0',
+    CLKOP  => clk_100_i,
+    CLKOK  => clk_200_i,
+    LOCK   => pll_lock
+    );
+  \end{verbatim}
+\item FSM coding style is up to each individual. Most code uses the single-process version, using just one single, synchronous process. This reduces the number of signals needed and fully avoids any potential issue with latches due to unassigned signals.
+\end{itemize*}
+
+
 %%% Local Variables:
 %%% mode: latex
 %%% TeX-master: "main"