There's the unwritten convention of splitting type names using
underscores. Add such convention to the CODINNG_STYLE to make it
common and less unwritten.
Signed-off-by: Alejandro Vallejo <agarciav@amd.com>
Acked-by: Stefano Stabellini <sstabellini@kernel.org>
Despite the best intentions at the time, the current recommendation
lead to very long identifiers, bordering on the max limit we've chosen
for certification.
One observation is that we do have static analysis which will
highlight if duplicate guards are created accidentally.
Therefore, relax the recommendations and in particular remove the
specific tie to the directory structure. This has the other advantage
of being more similar to other projects.
This will hopefully mean there's less churn getting the tree in shape,
and a random contributor is more likely to pick an appropriate guard
given no specific knowledge of Xen.
As always, it's something reviewers and maintainers should be aware
of, and to advise on.
Reviewed-by: Stefano Stabellini <sstabellini@kernel.org>
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Provide a (small) set of rules on how header guard identifiers ought to
be spelled and what precautions ought to be taken to avoid name
collisions.
Signed-off-by: Jan Beulich <jbeulich@suse.com>
Acked-by: Stefano Stabellini <sstabellini@kernel.org>
Today the CODING_STYLE contains a section "Handling unexpected
conditions" specific to the hypervisor. This section is kind of
misplaced for a coding style. It should rather be part of a "Coding
best practices" guide.
Add such a guide as docs/process/coding-best-practices.pandoc and
move the mentioned section from CODING_STYLE to the new file, while
converting the format to pandoc.
Signed-off-by: Juergen Gross <jgross@suse.com>
Acked-by: Julien Grall <jgrall@amazon.com>
Several maintainers have expressed a stronger preference
to use '-' when in filename and option that contains multiple
words.
So document it in CODING_STYLE.
Signed-off-by: Julien Grall <jgrall@amazon.com>
For easy spotting of struct/union/enum definitions we already commonly
place the opening braces on the initial line of such a definition.
We also often don't place the opening brace of an initializer on a
separate line.
And finally for compound literals placing the braces on separate lines
often makes the code more difficult to read, so it should (and in
practice does) typically go on the same line as well. The placement of
the closing brace often depends on how large such a compound literal is.
Signed-off-by: Jan Beulich <jbeulich@suse.com>
Acked-by: Stefano Stabellini <sstabellini@kernel.org>
Since the behavior of "diff -p" to use an unindented label as context
identifier often makes it harder to review patches, make explicit the
requirement for labels to be indented.
Signed-off-by: Jan Beulich <jbeulich@suse.com>
Acked-by: Stefano Stabellini <sstabellini@kernel.org>
Introduce a list of MISRA C rules that apply to the Xen hypervisor. The
list is in RST format.
Specify that rules deviations need to be documented. Introduce a
documentation tag for in-code comments to mark them as deviations. Also
mention that other documentation mechanisms are work-in-progress.
Add a mention of the new list to CODING_STYLE.
Signed-off-by: Stefano Stabellini <stefano.stabellini@xilinx.com>
Signed-off-by: Bertrand Marquis <bertrand.marquis@arm.com>
Acked-by: Julien Grall <jgrall@amazon.com>
It's not always clear what the best way is to handle unexpected
conditions: whether with ASSERT(), domain_crash(), BUG_ON(), or some
other method. All methods have a risk of introducing security
vulnerabilities and unnecessary instabilities to production systems.
Provide guidelines for different options and when to use them.
Signed-off-by: George Dunlap <george.dunlap@citrix.com>
Acked-by: Jan Beulich <jbeulich@suse.com>
Acked-by: Julien Grall <julien@xen.org>
One of the common ways in which contributors trip up over the
CODING_STYLE guides is by not putting a full stop at the end of a
comment when there is only a single sentence. Calling these out is a
waste of everybody's time: The full stop at the end of a comment with
a single sentence (or a single phrase) adds absolutely nothing to the
legibility of the code.
Modify CODING_STYLE to allow comments with a single sentence or
sentence fragment to either have a full stop or not, while making it
clear that comments with multiple sentences must have a full stop at
the end of each sentence.
Signed-off-by: George Dunlap <george.dunlap@citrix.com>
Acked-by: Ian Jackson <ian.jackson@citrix.com>
Alejandro Vallejo