Xastir coding standard.

The Xastir team uses Allman style code formatting. We use 2-space indents, vertical brace alignment, and will always use braces even when optional.

How Xastir was reformatted to fit the standard

The command we used to reformat all of the codebase was:

    astyle -A1 -s2 -S -xW -j -z2 *.h,*.c

in each directory containing code.

Setting up your editor to code in Xastir

Tabs

Set tabs to two characters, space filled. There should be no TAB characters appearing in the sources. For VIM, insert these lines into your ~/.vimrc file:

    :syntax on
    :set tabstop=2
    :set expandtab

For emacs, you should be able to use something like:

    (setq c-basic-indent 2)
    (setq tab-width 2)
    (c-set-offset 'substatement-open 0)
    (c-set-offset 'case-label '+)
    (setq indent-tabs-mode nil) 

Note that ".vimrc" files have been added to the Xastir project on Github, in every directory. Read that file for how to enable these directory-specific .vimrc files for a particular user.

For Emacs a project-specific config file was added to the top level of the Xastir project: ".dir-locals.el". Unfortunately, this mechanism can only set directory local variables, and cannot run specific emacs macros at a directory-local level. Therefore, the two "c-set-offset" lines still have to be done in your emacs startup file. The first makes sure the opening brace of a block is not indented, and the second assures that case labels are indented (emacs doesn't indent them by default, and would have them line up with the braces around a block instead).

Indentation

Indentation should be two spaces.

Braces

Bracing should be to the Allman standard (vertically aligned below the first character of the statement). Optional braces should ALWAYS be included.

    if ()
    {
        ....
    }
    else
    {
        ....
    }

Blank Lines

Put five blank lines between functions. This is to more easily see where each function begins.

Bug-fixes

Submit each bugfix or new feature as a separate pull request. This makes review, testing, and debugging of the patches easier. The preferred mechanism for handling user contributions is the pull request on github, using the "fork-and-pull-request" mechanism. That process is briefly described in Contributing, and in many, many online resources you can find by googling "fork and pull request workflow". Please do it that way.

Snprintf()

Don't use the snprintf() function. Use xastir_snprintf() instead. This is a macro that calls snprintf if your system provides it, but which runs an alternate version included in Xastir on systems that don't have snprintf (i.e really old systems).

CFLAGS

If you're debugging your code and trying to minimize the hassle for reviewers, you can build with additional CFLAGS to catch some common problems.

    -O2 -Wall -Wpointer-arith -Wstrict-prototypes -W -pedantic

Autoconf and Friends

The "bootstrap.sh" (or autoreconf -i) in the top level of the Xastir source tree must be run whenever building Xastir from a new git clone. This script creates configure and all the Makefile.in files it needs, by running aclocal, autoheader, autoconf and automake.

If acinclude.m4, configure.ac, or any Makefile.am has been changed you must rebuild 'configure' by rerunning the "bootstrap.sh" script.

Bumping Version Number

To bump the version number, change AC_INIT in configure.ac and then run bootstrap.

Language Files

If adding lines to one of the config/language* files, please add the same line to the other language files in English. Translators will eventually translate the English lines to the native languages.

Doing a Release

See the file "README.developers.md" in the Xastir source tree for details on what to do to create a release.