.TH "doc_CODING_md" 3elektra "Sun May 29 2016" "Version 0.8.14" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
doc_CODING_md \- CODING 
intensively (except for file header)\&.
.PP
This document provides an introduction in how the source code of libelektra is organized and how and where to add functionality\&.
.PP
Make sure to read \fBDESIGN\fP together with this document\&.
.PP
.SS "Folder structure"
.PP
After you downloaded and unpacked Elektra you see untypically many folders\&. The reason is that Elektra project consists of many activities\&.
.PP
The most important are:
.PP
.IP "\(bu" 2
\fBsrc:\fP Here is the source for the library and the tools itself\&.
.IP "\(bu" 2
\fBdoc:\fP Documentation for the library\&.
.IP "\(bu" 2
\fBexample:\fP Examples of using the library\&.
.IP "\(bu" 2
\fBtests:\fP Is the testing framework for the source\&.
.PP
.PP
.SS "Source Code"
.PP
libelektra is the ANSI/ISO C-Core which does interacts between the user and the plugins\&.
.PP
The plugins have all kinds of dependencies\&. It is the responsibility of the plugins to find and check them using CMake\&. The same guidelines apply for all code in the repository including the plugins\&.
.PP
\fClibloader\fP is responsible for loading the backend modules\&. It works for various operating systems by using \fClibltdl\fP, but has an optimized code for static linking and win32\&.
.PP
kdb is the commandline-tool to access and initialize the Elektra database\&.
.PP
.SS "General Guidelines"
.PP
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\&.
.PP
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\&.
.PP
If you see broken guidelines do not hesitate to fix them\&. At least put a TODO marker to make the places visible\&.
.PP
If you see inconsistency do not hesitate to talk about it with the intent to add a new rule here\&.
.PP
See \fBDESIGN\fP document too, they complement each other\&.
.PP
.SS "C Guidelines"
.PP
.IP "\(bu" 2
Functions should not exceed 100 lines\&.
.IP "\(bu" 2
Files should not exceed 1000 lines\&.
.IP "\(bu" 2
A line should not be longer then 72 characters\&.
.IP "\(bu" 2
Split up when those limits are reached\&.
.IP "\(bu" 2
Rationale: Readability with split windows\&.
.IP "\(bu" 2
The compiler shall not emit any warning (or error)\&.
.IP "\(bu" 2
Use tabs for indentation\&.
.IP "\(bu" 2
Prefer to use blocks to single line statements\&.
.IP "\(bu" 2
Curly braces go on a line on their own on the previous indentation level
.IP "\(bu" 2
Use goto only for error situations\&.
.IP "\(bu" 2
Use camelCase for functions and variables\&.
.IP "\(bu" 2
Start types with upper-case, everything else with lower-case\&.
.IP "\(bu" 2
Avoid spaces between words and round braces\&.
.IP "\(bu" 2
Use C-comments \fC/**/\fP with doxygen style for functions\&.
.IP "\(bu" 2
Use C++-comments \fC//\fP for single line statements about the code in the next line\&.
.IP "\(bu" 2
Avoid multiple variable declarations at one place and \fC*\fP are next to the variable names\&.
.IP "\(bu" 2
Use \fCconst\fP as much as possible\&.
.IP "\(bu" 2
Use \fCstatic\fP methods if they should not be externally visible\&.
.IP "\(bu" 2
Declare Variables as late as possible, preferable within blocks\&.
.IP "\(bu" 2
C-Files have extension \fC\&.c\fP, Header files \fC\&.h\fP\&.
.IP "\(bu" 2
Prefix names with \fCelektra\fP for internal usage\&. External API either starts with \fCks\fP, \fCkey\fP or \fCkdb\fP\&.
.PP
.PP
\fBExample:\fP \fCsrc/libelektra/kdb\&.c\fP
.PP
.SS "C++ Guidelines"
.PP
.IP "\(bu" 2
Everything as in C if not noted otherwise\&.
.IP "\(bu" 2
Do not use goto at all, use RAII instead\&.
.IP "\(bu" 2
Do not use raw pointers, use smart pointers instead\&.
.IP "\(bu" 2
C++-Files have extension \fC\&.cpp\fP, Header files \fC\&.hpp\fP\&.
.IP "\(bu" 2
Do not use \fCstatic\fP, but anonymous namespaces\&.
.IP "\(bu" 2
Write everything within namespaces and do not prefix names\&.
.PP
.PP
\fBExample:\fP \fCsrc/bindings/cpp/include/kdb\&.hpp\fP
.PP
.SS "Doxygen Guidelines"
.PP
\fCdoxygen\fP is used to document the API 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 \fCAPI Doc\fP online)\&. Links between markdown files will be converted with the \fBMarkdown Link Converter\fP\&. \fBMarkdown pages are used in the pdf, therefore watch your characters and provide a proper encoding!\fP
.PP
.IP "\(bu" 2
use \fC@\fP to start doxygen tags
.IP "\(bu" 2
Do not duplicate information available in git in doxygen\&.
.IP "\(bu" 2
Use \fC\\copydetails\fP, \fC@copybrief\fP and \fC@copydetails\fP intensively (except for file header)\&.
.PP
.PP
.SS "File Headers"
.PP
Files should start with:
.PP
.PP
.nf
        /**
         * @file
         *
         * @brief <short statement about the content of the file>
         *
         * @copyright BSD License (see doc/COPYING or http://www.libelektra.org)
         */.fi
.PP
.PP
Note:
.PP
.IP "\(bu" 2
` 
.PP