linuxptp/CODING_STYLE.org

• General
• Using checkpatch.pl
• Exceptions
  • Use of lowerCamelCase and UpperCamelCase
  • Braces around single if-else bodies
  • Line lengths

General

For this project, we are using the Linux kernel coding style, with a bit of latitude, as described below. The kernel style can be quickly summarized like this:

• text width is 80 columns
• indentation by tabs
• tab width is 8 spaces
• identifiers are lower case with underscores
• macros are upper case
• braces and spacing follow K&R style

Using checkpatch.pl

You can use the Linux kernel's checkpatch.pl script to sanity check your work. Sometimes that script warns about code which is in fact fine, so use your good taste. I use the following code as my pre-commit hook.

if git rev-parse --verify HEAD >/dev/null 2>&1
then
	against=HEAD
else
	# Initial commit: diff against an empty tree object
	against=4b825dc642cb6eb9a060e54bf8d69288fbee4904
fi

git diff --cached $against -- | ../linux/scripts/checkpatch.pl \
	--ignore BRACES \
	--ignore PREFER_PR_LEVEL \
	--no-signoff \
	-

Exceptions

Use of lowerCamelCase and UpperCamelCase

The messages and data sets in the PTP and gPTP standards are full of stuff that looks a bit like C-language pseudo code, and all this is unfortunately in camel case. In those cases where the linuxptp code is closely related to these fields, we retain the camel case, even though it hurts our eyes to look at.

The alternative would have been to convert the field names into lower case underscore, but that would have over extended the already ridiculously long names, such as logMinPdelayReqInterval and observedParentOffsetScaledLogVariance.

The exception permitting CamelCase applies primarily to the declarations found in the following header files.

• ddt.h
• ds.h
• msg.h
• pdt.h
• tlv.h

Braces around single if-else bodies

In the Linux kernel style, if-else bodies containing just a single line are not placed within curly braces. Therefore you will often see code like the following example.

	if (!x)
		do_zero();
	else
		do_nonzero();

In this situation we still like to see the braces, the rationale being that the if-else bodies tend to accumulate new statements over time, especially on the error path. Using the strict kernel style thus results in patches (and annotated views) that show a bogus change in the test expression, and this requires extra mental effort when reviewing patches, just to realize that no logical change has occurred. Additionally, having the braces hardly uses up more vertical space than not having them, so we generally include them as shown in the following example.

	if (!x) {
		do_zero();
	} else {
		do_nonzero();
	}

Line lengths

We try to keep the line length to 80 characters wide. However, sometimes it happens that, no matter how hard we try, we find ourselves going a bit over that limit. This is especially true in connection with the long CamelCase identifiers mentioned above. Breaking a statement over two lines can look even worse than having one line too long, so please exercise judgement when applying the line length rule.