|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
* General
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
For this project, we are using the Linux kernel coding style, with a
|
|
Packit |
9c3e7e |
bit of latitude, as described below. The kernel style can be quickly
|
|
Packit |
9c3e7e |
summarized like this:
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
- text width is 80 columns
|
|
Packit |
9c3e7e |
- indentation by tabs
|
|
Packit |
9c3e7e |
- tab width is 8 spaces
|
|
Packit |
9c3e7e |
- identifiers are lower case with underscores
|
|
Packit |
9c3e7e |
- macros are upper case
|
|
Packit |
9c3e7e |
- braces and spacing follow K&R style
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
* Using checkpatch.pl
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
You can use the Linux kernel's checkpatch.pl script to sanity check
|
|
Packit |
9c3e7e |
your work. Sometimes that script warns about code which is in fact
|
|
Packit |
9c3e7e |
fine, so use your good taste. I use the following code as my
|
|
Packit |
9c3e7e |
pre-commit hook.
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
#+BEGIN_EXAMPLE
|
|
Packit |
9c3e7e |
if git rev-parse --verify HEAD >/dev/null 2>&1
|
|
Packit |
9c3e7e |
then
|
|
Packit |
9c3e7e |
against=HEAD
|
|
Packit |
9c3e7e |
else
|
|
Packit |
9c3e7e |
# Initial commit: diff against an empty tree object
|
|
Packit |
9c3e7e |
against=4b825dc642cb6eb9a060e54bf8d69288fbee4904
|
|
Packit |
9c3e7e |
fi
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
git diff --cached $against -- | ../linux/scripts/checkpatch.pl \
|
|
Packit |
9c3e7e |
--ignore BRACES \
|
|
Packit |
9c3e7e |
--ignore PREFER_PR_LEVEL \
|
|
Packit |
9c3e7e |
--no-signoff \
|
|
Packit |
9c3e7e |
-
|
|
Packit |
9c3e7e |
#+END_EXAMPLE
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
* Exceptions
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
** Use of lowerCamelCase and UpperCamelCase
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
The messages and data sets in the PTP and gPTP standards are full
|
|
Packit |
9c3e7e |
of stuff that looks a bit like C-language pseudo code, and all this
|
|
Packit |
9c3e7e |
is unfortunately in camel case. In those cases where the linuxptp
|
|
Packit |
9c3e7e |
code is closely related to these fields, we retain the camel case,
|
|
Packit |
9c3e7e |
even though it hurts our eyes to look at.
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
The alternative would have been to convert the field names into
|
|
Packit |
9c3e7e |
lower case underscore, but that would have over extended the
|
|
Packit |
9c3e7e |
already ridiculously long names, such as logMinPdelayReqInterval
|
|
Packit |
9c3e7e |
and observedParentOffsetScaledLogVariance.
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
The exception permitting CamelCase applies primarily to the
|
|
Packit |
9c3e7e |
declarations found in the following header files.
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
- ddt.h
|
|
Packit |
9c3e7e |
- ds.h
|
|
Packit |
9c3e7e |
- msg.h
|
|
Packit |
9c3e7e |
- pdt.h
|
|
Packit |
9c3e7e |
- tlv.h
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
** Braces around single if-else bodies
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
In the Linux kernel style, if-else bodies containing just a single
|
|
Packit |
9c3e7e |
line are not placed within curly braces. Therefore you will often
|
|
Packit |
9c3e7e |
see code like the following example.
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
#+BEGIN_EXAMPLE
|
|
Packit |
9c3e7e |
if (!x)
|
|
Packit |
9c3e7e |
do_zero();
|
|
Packit |
9c3e7e |
else
|
|
Packit |
9c3e7e |
do_nonzero();
|
|
Packit |
9c3e7e |
#+END_EXAMPLE
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
In this situation we still like to see the braces, the rationale
|
|
Packit |
9c3e7e |
being that the if-else bodies tend to accumulate new statements
|
|
Packit |
9c3e7e |
over time, especially on the error path. Using the strict kernel
|
|
Packit |
9c3e7e |
style thus results in patches (and annotated views) that show a
|
|
Packit |
9c3e7e |
bogus change in the test expression, and this requires extra mental
|
|
Packit |
9c3e7e |
effort when reviewing patches, just to realize that no logical
|
|
Packit |
9c3e7e |
change has occurred. Additionally, having the braces hardly uses up
|
|
Packit |
9c3e7e |
more vertical space than not having them, so we generally include
|
|
Packit |
9c3e7e |
them as shown in the following example.
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
#+BEGIN_EXAMPLE
|
|
Packit |
9c3e7e |
if (!x) {
|
|
Packit |
9c3e7e |
do_zero();
|
|
Packit |
9c3e7e |
} else {
|
|
Packit |
9c3e7e |
do_nonzero();
|
|
Packit |
9c3e7e |
}
|
|
Packit |
9c3e7e |
#+END_EXAMPLE
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
** Line lengths
|
|
Packit |
9c3e7e |
|
|
Packit |
9c3e7e |
We try to keep the line length to 80 characters wide. However,
|
|
Packit |
9c3e7e |
sometimes it happens that, no matter how hard we try, we find
|
|
Packit |
9c3e7e |
ourselves going a bit over that limit. This is especially true in
|
|
Packit |
9c3e7e |
connection with the long CamelCase identifiers mentioned above.
|
|
Packit |
9c3e7e |
Breaking a statement over two lines can look even worse than having
|
|
Packit |
9c3e7e |
one line too long, so please exercise judgement when applying the
|
|
Packit |
9c3e7e |
line length rule.
|