288 lines
7.0 KiB
Plaintext
288 lines
7.0 KiB
Plaintext
|
|
trace-cmd coding-style
|
|
======================
|
|
|
|
The coding style of trace-cmd and the tracing libraries (libtracefs and
|
|
libtraceevent) are very similar to the Linux kernel coding style:
|
|
|
|
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/coding-style.rst
|
|
|
|
Indentation
|
|
===========
|
|
|
|
Tabs are used for the start of indentation (the '\t' character), and should be
|
|
set to 8 characters. Spaces may be used at the end for continued lines where
|
|
having the start of text line up to braces in the previous line is not
|
|
divisible by 8.
|
|
|
|
Max line width
|
|
==============
|
|
|
|
All lines should not be more than 100 characters in length.
|
|
|
|
This is a guide, as readability is more important than breaking lines up into a
|
|
hard limit. Ideally, strings should never be broken up except for where a new
|
|
line is added.
|
|
|
|
printf("This is a line that may continue for a very long string.\n"
|
|
"This is another line, but after a new line\n");
|
|
|
|
But line breaks should not be:
|
|
|
|
printf("This is a line that may continue for a very"
|
|
"long string.\n This is another line,"
|
|
"but after a new line\n");
|
|
|
|
Not only is the above not as readable as the first version, it is not
|
|
even equivalent, because it is missing spaces between the line breaks.
|
|
For this reason, finish the string on the same line, even if that string
|
|
breaks the 100 character limit.
|
|
|
|
Brackets and braces
|
|
===================
|
|
|
|
For all conditionals, the braces start on the same line:
|
|
|
|
if (cond) {
|
|
}
|
|
|
|
And the ending brace is at the same indentation as the conditional.
|
|
|
|
while (cond) {
|
|
}
|
|
|
|
do {
|
|
} while (cond);
|
|
|
|
for (i = 0; i < 10; i++) {
|
|
}
|
|
|
|
The same is true for structures:
|
|
|
|
struct my_struct {
|
|
int field;
|
|
};
|
|
|
|
But for functions, the braces should start on the following line:
|
|
|
|
void my_function(void)
|
|
{
|
|
}
|
|
|
|
|
|
It is also fine to not use braces for simple conditionals and loops.
|
|
|
|
if (!x)
|
|
y = x;
|
|
else
|
|
y = 1;
|
|
|
|
for (i = 0; i < 10; i++)
|
|
foo(i);
|
|
|
|
while (getline(&line, &size, fp) > 0)
|
|
printf("%s", line);
|
|
|
|
But any complex or multiline conditional or loop should have braces even if it
|
|
is allowed not to by the C language.
|
|
|
|
if (x) {
|
|
for (i = 0; i < 10; i++)
|
|
foo(i);
|
|
} else {
|
|
foo(1);
|
|
}
|
|
|
|
Notice above that even though the else portion is simple, it too has braces as
|
|
the else and if blocks should match. If one is required to have braces, they
|
|
both should have braces.
|
|
|
|
|
|
Spaces
|
|
======
|
|
|
|
A single space should be used between C commands and their starting
|
|
parenthesis.
|
|
|
|
if (x)
|
|
for (i = 0; i < 10; i++)
|
|
while (getline(&line, &size, fp) > 0)
|
|
|
|
There should be no space between function or macros and the starting
|
|
parenthesis.
|
|
|
|
foo(x)
|
|
IS_VALID(y)
|
|
|
|
This includes prototypes and declarations.
|
|
|
|
void foo(int x)
|
|
|
|
A space should be before and after assignment, comparison and algorithmic
|
|
signs.
|
|
|
|
i = 0;
|
|
if (i < 10)
|
|
if (i == 5)
|
|
|
|
y = i + 10;
|
|
|
|
i += 5;
|
|
|
|
For structures, use tabs to make all the fields line up nicely.
|
|
|
|
struct {
|
|
int foo;
|
|
int bar;
|
|
unsigned long long time;
|
|
};
|
|
|
|
Variable declarations
|
|
=====================
|
|
|
|
The order of variables that are declared, should first keep the same types
|
|
together, but also should be ordered by their length such that the variables
|
|
are ordered in an "upside-down Christmas tree" fashion where the length gets
|
|
smaller.
|
|
|
|
int tracecmd_count_cpus(void)
|
|
{
|
|
static int once;
|
|
char buf[1024];
|
|
int cpus = 0;
|
|
char *pbuf;
|
|
size_t *pn;
|
|
FILE *fp;
|
|
size_t n;
|
|
int r;
|
|
|
|
The above shows that the order is done by length, and in the above example it
|
|
also shows that "int cpu = 0;" is not grouped next to "int r;". As this is more
|
|
of a guideline and made to be more aesthetic to the eye of the reader, both the
|
|
above and is acceptable as below.
|
|
|
|
int tracecmd_count_cpus(void)
|
|
{
|
|
static int once;
|
|
char buf[1024];
|
|
char *pbuf;
|
|
size_t *pn;
|
|
FILE *fp;
|
|
size_t n;
|
|
int cpus = 0;
|
|
int r;
|
|
|
|
|
|
Unless variables are tightly related, it is expected that each variable be on
|
|
its own line and not grouped by type. That is,
|
|
|
|
int r, cpus = 0;
|
|
|
|
is to be discouraged, as the two variables are not related to each other.
|
|
But if you had a bunch of counters:
|
|
|
|
int i, j, k;
|
|
|
|
That would be fine, as the variables are all related as they are all for the
|
|
same purpose (arbitrary counters). The same may go with pointers;
|
|
|
|
|
|
char *begin, *end;
|
|
|
|
Comments
|
|
========
|
|
|
|
Comments will use the "/* */" format and the C++ "//" style is discouraged.
|
|
If a comment is on one line, keep the "/*" and "*/" on the same line:
|
|
|
|
/* This is a single line comment. */
|
|
|
|
If a comment spans more than one line, then have the "/*" on a separate line
|
|
before the comment and the "*/" on a separate line at the end of the comment,
|
|
and each line starts with a "*" where all the "*" line up with each other.
|
|
|
|
/*
|
|
* This is a multi line comment, where all the '*'
|
|
* will line up, and the text is on a separate line
|
|
* as the start and end markers.
|
|
*/
|
|
|
|
|
|
Function documentation
|
|
======================
|
|
|
|
All global functions (and especially any APIs) should have a function
|
|
description in the form of "kernel doc":
|
|
|
|
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html
|
|
|
|
The form is:
|
|
|
|
/**
|
|
* function_name() - Brief description of function.
|
|
* @arg1: Describe the first argument.
|
|
* @arg2: Describe the second argument.
|
|
* One can provide multiple line descriptions
|
|
* for arguments.
|
|
*
|
|
* A longer description, with more discussion of the function function_name()
|
|
* that might be useful to those using or modifying it. Begins with an
|
|
* empty comment line, and may include additional embedded empty
|
|
* comment lines.
|
|
*
|
|
* The longer description may have multiple paragraphs.
|
|
*
|
|
* Context: Describes whether the function can sleep, what locks it takes,
|
|
* releases, or expects to be held. It can extend over multiple
|
|
* lines.
|
|
* Return: Describe the return value of function_name.
|
|
*
|
|
* The return value description can also have multiple paragraphs, and should
|
|
* be placed at the end of the comment block.
|
|
*/
|
|
|
|
Structure layout
|
|
================
|
|
|
|
This is more about compaction than coding style. When creating structures, be
|
|
aware that if the fields are placed together without being sized by alignment,
|
|
that the compiler will create "holes" in them.
|
|
|
|
struct {
|
|
int x;
|
|
char y;
|
|
unsigned long long f;
|
|
};
|
|
|
|
As int is 4 bytes in length, char is one byte, and unsigned long long is 8
|
|
bytes. The compiler will try to naturally align them by their size, and will
|
|
include padding (holes) inside the structure to do so. The above is equivalent
|
|
to:
|
|
|
|
struct {
|
|
int x;
|
|
char y;
|
|
char padding[3];
|
|
unsigned long long f;
|
|
};
|
|
|
|
It is best to try to organize the structure where there are no holes within
|
|
them.
|
|
|
|
struct {
|
|
unsigned long long f;
|
|
int x;
|
|
char y;
|
|
};
|
|
|
|
The above is better formatting, even if there may be padding outside the
|
|
structure, but the compiler will still have more flexibility to utilize the
|
|
space outside the structure than what it can do within it.
|
|
|
|
General
|
|
=======
|
|
|
|
As stated, this is a guide and may not be strictly enforced. The goal is to
|
|
have consistent and readable code. In general, try to have the coding style
|
|
match the surrounding code.
|