intensively (except for file headers).

This document provides an introduction in how the source code of libelektra is organized and how and where to add functionality.

Make sure to read \hyperlink{doc_DESIGN_md}{D\+E\+S\+I\+G\+N} together with this document.

\subsection*{Folder structure}

After you downloaded and unpacked Elektra you should see some folders. The most important are\+:


\begin{DoxyItemize}
\item {\bfseries src\+:} This directory contains the source of the libraries, tools and plugins.
\item {\bfseries doc\+:} General documentation for the project and the core library.
\item {\bfseries examples\+:} Examples on how to use the core library.
\item {\bfseries tests\+:} Contains the testing framework for the source ({\bfseries src}).
\end{DoxyItemize}

\subsection*{Source Code}

libelektra is the A\+N\+S\+I/\+I\+S\+O C99-\/\+Core which coordinates the interactions between the user and the plugins.

The plugins have all kinds of dependencies. It is the responsibility of the plugins to find and check them using C\+Make. The same guidelines apply to all code in the repository including the plugins.

{\ttfamily libloader} is responsible for loading the backend modules. It works on various operating systems by using {\ttfamily libltdl}. This code is optimized for static linking and win32.

kdb is the commandline-\/tool to access and initialize the Elektra database.

\subsubsection*{General Guidelines}

You are only allowed to break a guideline if there is a good reason to do so. When you do, document the fact as comment next to the code.

Of course, all rules of good software engineering apply\+: Use meaningful names and keep the software both testable and reusable.

The purpose of the guidelines is to have a consistent style, not to teach programming.

If you see code that breaks guidelines do not hesitate to fix them. At least put a T\+O\+D\+O marker to make the places visible.

If you see inconsistency within the rules do not hesitate to talk about it with the intent to add a new rule here.

See \hyperlink{doc_DESIGN_md}{D\+E\+S\+I\+G\+N} document too, they complement each other.

\subsubsection*{Code Comments}

Code is not only for the computer, but it should be readable for humans, too. Up-\/to-\/date code comments are essential to make code understandable for others. Thus please use following techniques (in order of preference)\+:


\begin{DoxyEnumerate}
\item Comment functions with {\ttfamily /$\ast$$\ast$/} and Doxygen, see below.
\item You should use also add assertions to state what should be true at a specific position in the code. Their syntax is checked and they are automatically verified at run-\/time. So they are not only useful for people reading the code but also for tools. Assertions in Elektra are used by\+:

{\ttfamily \#include $<$\hyperlink{kdbassert_8h}{kdbassert.\+h}$>$}

{\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+A\+S\+S\+E\+R\+T (condition, \char`\"{}formatted text to be printed when assert fails\char`\"{}, ...)}

Note\+: Do not use assert for user-\/\+A\+P\+Is, always handle arguments of user-\/\+A\+P\+Is like untrusted input.
\item If the \char`\"{}comment\char`\"{} might be useful to be printed during execution, use logging\+:

{\ttfamily \#include $<$\hyperlink{kdblogger_8h}{kdblogger.\+h}$>$}

{\ttfamily E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+G (\char`\"{}formatted text to be printed according log filters\char`\"{}, ...)}

There are four log levels\+:
\begin{DoxyItemize}
\item E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+G\+\_\+\+W\+A\+R\+N\+I\+N\+G, something critical that should be shown the user (e.\+g. A\+P\+I misuse), see \hyperlink{kdblogger_8h_a4096a2ccd61c6f5ad60e9015fd1bbb4ba0524fff5c46e0cf07287c473c46cc8e2}{E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+G\+\_\+\+L\+E\+V\+E\+L\+\_\+\+W\+A\+R\+N\+I\+N\+G}
\item E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+G\+\_\+\+N\+O\+T\+I\+C\+E, something important developers are likely interested in, see \hyperlink{kdblogger_8h_a4096a2ccd61c6f5ad60e9015fd1bbb4ba329fc1e04c797ab8e54a137b21f41baf}{E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+G\+\_\+\+L\+E\+V\+E\+L\+\_\+\+N\+O\+T\+I\+C\+E}
\item E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+G, standard level gives information what the code is doing without flooding the log, see \hyperlink{kdblogger_8h_a4096a2ccd61c6f5ad60e9015fd1bbb4ba01618746c91d9d1090f599f604b9b832}{E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+G\+\_\+\+L\+E\+V\+E\+L\+\_\+\+I\+N\+F\+O}
\item E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+G\+\_\+\+D\+E\+B\+U\+G, for less important logs, see \hyperlink{kdblogger_8h_a4096a2ccd61c6f5ad60e9015fd1bbb4ba24c7a4c44a8b99b978dc99806d083386}{E\+L\+E\+K\+T\+R\+A\+\_\+\+L\+O\+G\+\_\+\+L\+E\+V\+E\+L\+\_\+\+D\+E\+B\+U\+G}
\end{DoxyItemize}
\item Otherwise comment within source with {\ttfamily //} or with {\ttfamily /$\ast$$\ast$/} for multi-\/line comments.
\end{DoxyEnumerate}

\subsubsection*{Coding Style}


\begin{DoxyItemize}
\item Limits
\begin{DoxyItemize}
\item Functions should not exceed 100 lines.
\item Files should not exceed 1000 lines.
\item A line should not be longer than 140 characters.
\end{DoxyItemize}
\end{DoxyItemize}

Split up when those limits are reached. Rationale\+: Readability with split windows.


\begin{DoxyItemize}
\item Indentation
\begin{DoxyItemize}
\item Use tabs for indentation.
\item One tab equals 8 spaces.
\end{DoxyItemize}
\item Blocks
\begin{DoxyItemize}
\item Use blocks even for single line statements.
\item Curly braces go on a line on their own on the previous indentation level.
\item Avoid multiple variable declarations at one place.
\item Declare Variables as late as possible, preferable within blocks.
\end{DoxyItemize}
\item Naming
\begin{DoxyItemize}
\item Use camel\+Case for functions and variables.
\item Start types with upper-\/case, everything else with lower-\/case.
\item Prefix names with {\ttfamily elektra} for internal usage. External A\+P\+I either starts with {\ttfamily ks}, {\ttfamily key} or {\ttfamily kdb}.
\end{DoxyItemize}
\item Whitespaces
\begin{DoxyItemize}
\item Use space before and after equal when assigning a value.
\item Use space before round parenthesis ( {\ttfamily (} ).
\item Use space before and after {\ttfamily $\ast$} from Pointers.
\item Use space after {\ttfamily ,} of every function argument.
\end{DoxyItemize}
\end{DoxyItemize}

The reformat script can ensure most code style rules, but it is obviouly not capable of ensuring everything (e.\+g. naming conventions). So do not give this responsibility out of hands entirely.

\subsubsection*{C Guidelines}


\begin{DoxyItemize}
\item The compiler shall not emit any warning (or error).
\item Use goto only for error situations.
\item Use {\ttfamily const} as much as possible.
\item Use {\ttfamily static} methods if they should not be externally visible.
\item C-\/\+Files have extension {\ttfamily .c}, Header files {\ttfamily .h}.
\end{DoxyItemize}

{\bfseries Example\+:} \href{/home/markus/Projekte/Elektra/current/src/libs/elektra/kdb.c}{\tt src/libs/elektra/kdb.\+c}

\subsubsection*{C++ Guidelines}


\begin{DoxyItemize}
\item Everything as in C if not noted otherwise.
\item Do not use goto at all, use R\+A\+I\+I instead.
\item Do not use raw pointers, use smart pointers instead.
\item C++-\/\+Files have extension {\ttfamily .cpp}, Header files {\ttfamily .hpp}.
\item Do not use {\ttfamily static}, but anonymous namespaces.
\item Write everything within namespaces and do not prefix names.
\item Oriented towards https\+://github.com/isocpp/\+Cpp\+Core\+Guidelines/blob/master/\+Cpp\+Core\+Guidelines.\+md \char`\"{}more safe and modern usage\char`\"{}.
\end{DoxyItemize}

{\bfseries Example\+:} \href{/home/markus/Projekte/Elektra/current/src/bindings/cpp/include/kdb.hpp}{\tt src/bindings/cpp/include/kdb.\+hpp}

\subsubsection*{Doxygen Guidelines}

{\ttfamily doxygen} is used to document the A\+P\+I and to build the html and pdf output. We also support the import of Markdown pages. Doxygen 1.\+8.\+8 or later is required for this feature (Anyways you can find the \href{http://doc.libelektra.org/api/latest/html/}{\tt A\+P\+I Doc} online). Links between Markdown files will be converted with the \hyperlink{doc_markdownlinkconverter_README_md}{Markdown Link Converter}. {\bfseries Markdown pages are used in the pdf, therefore watch which characters you use and provide a proper encoding!}


\begin{DoxyItemize}
\item use {\ttfamily @} to start Doxygen tags
\item Do not duplicate information available in git in Doxygen comments.
\item Use {\ttfamily \textbackslash{}copydetails}, {\ttfamily @copybrief} and {\ttfamily @copydetails} intensively (except for file headers).
\end{DoxyItemize}

\subsubsection*{File Headers}

Files should start with\+:

\begin{DoxyVerb}        /**
         * @file
         *
         * @brief <short statement about the content of the file>
         *
         * @copyright BSD License (see doc/LICENSE.md or http://www.libelektra.org)
         */\end{DoxyVerb}


Note\+:


\begin{DoxyItemize}
\item {\ttfamily @} {\ttfamily file} has {\itshape no} parameters.
\item {\ttfamily @} {\ttfamily brief} should contain a short statement about the content of the file and is needed so that your file gets listed at \href{http://doc.libelektra.org/api/latest/html/files.html}{\tt http\+://doc.\+libelektra.\+org/api/latest/html/files.\+html}
\end{DoxyItemize}

The duplication of the filename, author and date is not needed, because this information is tracked using git and doc/\+A\+U\+T\+H\+O\+R\+S already. 