intensively (except for file header).

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 see untypically many folders. The reason is that Elektra project consists of many activities.

The most important are\+:


\begin{DoxyItemize}
\item {\bfseries src\+:} Here is the source for the library and the tools itself.
\item {\bfseries doc\+:} Documentation for the library.
\item {\bfseries example\+:} Examples of using the library.
\item {\bfseries tests\+:} Is the testing framework for the source.
\end{DoxyItemize}

\subsection*{Source Code}

libelektra is the A\+N\+S\+I/\+I\+S\+O C-\/\+Core which does interacts 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 for all code in the repository including the plugins.

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

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

\subsubsection*{General Guidelines}

It is only allowed to break a guideline if there is a good reason for it. When doing so, document the fact either in the commit message, or as comment next to the code.

Of course all rules of good software engineering apply, like to use good names, make software testable and reusable. The purpose of the guidelines is to have a consistent style, not to teach programming.

If you see broken 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 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*{C Guidelines}


\begin{DoxyItemize}
\item Functions should not exceed 100 lines.
\item Files should not exceed 1000 lines.
\item A line should not be longer then 72 characters.
\item Split up when those limits are reached.
\item Rationale\+: Readability with split windows.
\item The compiler shall not emit any warning (or error).
\item Use tabs for indentation.
\item Prefer to use blocks to single line statements.
\item Curly braces go on a line on their own on the previous indentation level
\item Use goto only for error situations.
\item Use camel\+Case for functions and variables.
\item Start types with upper-\/case, everything else with lower-\/case.
\item Avoid spaces between words and round braces.
\item Use C-\/comments {\ttfamily /$\ast$$\ast$/} with doxygen style for functions.
\item Use C++-\/comments {\ttfamily //} for single line statements about the code in the next line.
\item Avoid multiple variable declarations at one place and {\ttfamily $\ast$} are next to the variable names.
\item Use {\ttfamily const} as much as possible.
\item Use {\ttfamily static} methods if they should not be externally visible.
\item Declare Variables as late as possible, preferable within blocks.
\item C-\/\+Files have extension {\ttfamily .c}, Header files {\ttfamily .h}.
\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}

{\bfseries Example\+:} \href{../src/libelektra/kdb.c}{\tt src/libelektra/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.
\end{DoxyItemize}

{\bfseries Example\+:} \href{http://libelektra.org/tree/master/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 support also the import of markdown pages, but a minimum version of 1.\+8.\+8 of Doxygen 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 your characters and provide a proper encoding!}


\begin{DoxyItemize}
\item use {\ttfamily @} to start doxygen tags
\item Do not duplicate information available in git in doxygen.
\item Use {\ttfamily \textbackslash{}copydetails}, {\ttfamily @copybrief} and {\ttfamily @copydetails} intensively (except for file header).
\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/COPYING or http://www.libelektra.org)
         */\end{DoxyVerb}


Note\+:


\begin{DoxyItemize}
\item ` 
\end{DoxyItemize}