/*! @page contributing_code Guide for Contributors

# Introduction #

This document describes the code style to be used when contributing to
the PIO library.

Consistency of style allows bugs to be spotted more quickly and
contributes to code quality.

# C Code #

## Warnings ##

<p>The C library compiles under GNU gcc without warnings. No code will
be merged with the C library which causes warnings during compile.

## Backward Compatibility ##

<p>We cannot remove or change a function in the public C API. We can
add to it, carefully.

## Brevity ##

<p>Consider: C is a terse language.

<ul>
<li>Use the fact that NULL == 0, and 0 == false, to shorten code.
<li>Assign and check return values in the same if statement.
</ul>

## Indentation and Spacing##

<ul>
<li>Use spaces not tabs.
<li>4 spaces is the unit of intendation.
<li>Indentation as defined by the "linux" style in emacs (see below).
<li>Use spaces around most operators (= + - * /) not pointer or prefix/postfile (* ++ --)
<li>Spaces after most keywords (if, for, while, etc.)
<li>No spaces after function name.
</ul>

## Braces ##

<p>Put braces on their own line, avoiding their use if possible.

## Documentation ##

<ul>
<li>Every function must be documented using doxygen.
<li>Keep internal functions in separate code files, so that Doxygen
can easily build user and development builds of the documentation.
<li>Use the doxygen \@ingroup to put public functions in the correct
group.
<li>Code must be reasonably documented as to intention.
<li>Documentation quality and quantity are part of code review
process.
<li>Document in complete sentences.
<li>Use C (not C++) comment delimiters.
<li>Use the author tag to indicate which programmers have worked on
each function. When adding or changing a function in a non-trivial
way, programmers should add their name to the end of the list of
authors for that function.
</ul>

## Emacs ##

<p>Put this in your .emacs file:

<pre>
(setq c-default-style "linux"
          c-basic-offset 4)
</pre>

<p>The tab key (used anywhere on the line) will indent a line
correctly. M-x indent-region will indent a selected region of code.

<p>M-x untabify will convert all the tabs in a file to spaces.

## Code Review ##

<ul>

<li>All code is subject to review.

<li>Pull requests will be focused on one issue.

<li>Pull requests may not be submitted until all tests pass.

<li>All non-trivial pull requests are associated with a github
issue. The issue is where discussion of requirements and
implementation details can be worked out.

<li>Pull requests will be left up on github for about a day. Request
more time if you need it and are actively reviewing the code. (Note
that pull request can also be reviewed after they are merged, if you
miss one).

<li>Jim will identify key stakeholders in changed code and ensure they
accept code changes.

<li>Reviewers are open-minded and ready to accept improvements to the
library.

<li>Reviewers will make comments on the pull request. All comments
must be resolved.

<li>If chages are dictated, they happen on the branch, so code
reviewers can see the updated code.

<li>The pull request is only merged when all programmers agree that
all issues have been resolved.

</ul>

## Merge Proceedure

<ul>

<li>Programmers begin work on a feature or fix by branching from
master.

<li>When a branch is ready, it is submitted to code review via pull
request. A number of Github tests will be run automatically. 

<li>When code review is complete, and the changes are approved, the PR
is merged into the master branch.

<li>The master branch is tested periodically by CDash (every ~6
hours). Any test failures and the merge to master may be rolled back.

<li>The branch is then deleted by whomever merged it to master.

</ul>


*/
