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

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

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

Brevity

Consider: C is a terse language.

• Use the fact that NULL == 0, and 0 == false, to shorten code.
• Assign and check return values in the same if statement.

Indentation and Spacing

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

Braces

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

Documentation

• Every function must be documented using doxygen.
• Keep internal functions in separate code files, so that Doxygen can easily build user and development builds of the documentation.
• Use the doxygen @ingroup to put public functions in the correct group.
• Code must be reasonably documented as to intention.
• Documentation quality and quantity are part of code review process.
• Document in complete sentences.
• Use C (not C++) comment delimiters.
• 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.

Emacs

Put this in your .emacs file:

(setq c-default-style "linux"
          c-basic-offset 4)

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

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

Code Review

• All code is subject to review.

• Pull requests will be focused on one issue.

• Pull requests may not be submitted until all tests pass.

• 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.

• 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).

• Jim will identify key stakeholders in changed code and ensure they accept code changes.

• Reviewers are open-minded and ready to accept improvements to the library.

• Reviewers will make comments on the pull request. All comments must be resolved.

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

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

Merge Proceedure

• Programmers begin work on a feature or fix by branching from master.

• When a branch is ready, it is submitted to code review via pull request. Travis CI testing is automatically run on the PR.

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

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

• The branch is then deleted by whomever merged it to master.