Changeset View
Standalone View
share/man/man9/style.9
.\"- | .\"- | |||||||||
.\" Copyright (c) 1995-2022 The FreeBSD Project | .\" Copyright (c) 1995-2022 The FreeBSD Project | |||||||||
pauamma_gundo.comUnsubmitted Not Done Inline Actions
pauamma_gundo.com: | ||||||||||
.\" | .\" | |||||||||
.\" Redistribution and use in source and binary forms, with or without | .\" Redistribution and use in source and binary forms, with or without | |||||||||
.\" modification, are permitted provided that the following conditions | .\" modification, are permitted provided that the following conditions | |||||||||
.\" are met: | .\" are met: | |||||||||
.\" 1. Redistributions of source code must retain the above copyright | .\" 1. Redistributions of source code must retain the above copyright | |||||||||
.\" notice, this list of conditions and the following disclaimer. | .\" notice, this list of conditions and the following disclaimer. | |||||||||
.\" 2. Redistributions in binary form must reproduce the above copyright | .\" 2. Redistributions in binary form must reproduce the above copyright | |||||||||
.\" notice, this list of conditions and the following disclaimer in the | .\" notice, this list of conditions and the following disclaimer in the | |||||||||
Show All 9 Lines | ||||||||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |||||||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |||||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |||||||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | |||||||||
.\" | .\" | |||||||||
.\" From: @(#)style 1.14 (Berkeley) 4/28/95 | .\" From: @(#)style 1.14 (Berkeley) 4/28/95 | |||||||||
.\" $FreeBSD$ | .\" $FreeBSD$ | |||||||||
.\" | .\" | |||||||||
.Dd July 28, 2022 | .Dd July 28, 2022 | |||||||||
Not Done Inline ActionsBump. pauamma_gundo.com: Bump. | ||||||||||
.Dt STYLE 9 | .Dt STYLE 9 | |||||||||
.Os | .Os | |||||||||
.Sh NAME | .Sh NAME | |||||||||
.Nm style | .Nm style | |||||||||
.Nd "kernel source file style guide" | .Nd "kernel source file style guide" | |||||||||
.Sh DESCRIPTION | .Sh DESCRIPTION | |||||||||
This file specifies the preferred style for kernel source files in the | This file specifies the preferred style for kernel source files in the | |||||||||
.Fx | .Fx | |||||||||
source tree. | source tree. | |||||||||
It is also a guide for the preferred userland code style. | It is also a guide for the preferred userland code style. | |||||||||
The preferred line width is 80 characters, but some exceptions are | The preferred line width is 80 characters, but some exceptions are | |||||||||
made when a slightly longer line is clearer or easier to read. | made when a slightly longer line is clearer or easier to read. | |||||||||
Anything that is frequently grepped for, such as diagnostic, error, or panic | Anything that is frequently grepped for, such as diagnostic, error, or panic | |||||||||
Not Done Inline Actions
pauamma_gundo.com: | ||||||||||
messages, should not be broken up over multiple lines despite this rule. | messages, should not be broken up over multiple lines despite this rule. | |||||||||
Many of the style rules are implicit in the examples. | Many of the style rules are implicit in the examples. | |||||||||
Be careful to check the examples before assuming that | Be careful to check the examples before assuming that | |||||||||
.Nm | .Nm | |||||||||
is silent on an issue. | is silent on an issue. | |||||||||
.Bd -literal | .Bd -literal | |||||||||
/* | /* | |||||||||
* Style guide for FreeBSD. Based on the CSRG's KNF (Kernel Normal Form). | * Style guide for FreeBSD. Based on the CSRG's KNF (Kernel Normal Form). | |||||||||
▲ Show 20 Lines • Show All 480 Lines • ▼ Show 20 Lines | ||||||||||
.Ic switch | .Ic switch | |||||||||
cascade. | cascade. | |||||||||
Elements in a | Elements in a | |||||||||
.Ic switch | .Ic switch | |||||||||
statement that cascade should have a | statement that cascade should have a | |||||||||
.Li FALLTHROUGH | .Li FALLTHROUGH | |||||||||
comment. | comment. | |||||||||
Numerical arguments should be checked for accuracy. | Numerical arguments should be checked for accuracy. | |||||||||
Code which is unreachable for non-obvious reasons may be marked /* | Code which is unreachable for non-obvious reasons may be marked /* | |||||||||
Done Inline ActionsWe have only 307 NOTREACHEDs in the tree, in 121 files. annotations (like __dead2 or __assert_unreachable as some folks mentioned on IRC) are much better emaste: We have only 307 `NOTREACHED`s in the tree, in 121 files. annotations (like `__dead2` or… | ||||||||||
Done Inline ActionsCode which is unreachable for non-obvious reasons should be marked accordingly. In the kernel, .Fn __assert_unreachable should be used in preference to the older /* .Li NOTREACHED */. That annotation is not available in userland, so use /* .Li NOTREACHED */ there instead. rpokala: ```
Code which is unreachable for non-obvious reasons should be marked accordingly.
In the… | ||||||||||
Done Inline ActionsI'd rather just expose __assert_unreachable in userland. I don't read the previous version as encouraging the use of annotations, just permitting them. The new version reads to me as if it more strongly mandates it. That is, I feel like the old use of may here was actually correct. jhb: I'd rather just expose __assert_unreachable in userland.
I don't read the previous version as… | ||||||||||
Done Inline ActionsI think I'll drop these chunks of the change as 'premature' then. We'll revisit once we have different interfaces and want a stronger encouragement. imp: I think I'll drop these chunks of the change as 'premature' then. We'll revisit once we have… | ||||||||||
.Li NOTREACHED | .Li NOTREACHED | |||||||||
*/. | */. | |||||||||
.Bd -literal | .Bd -literal | |||||||||
while ((ch = getopt(argc, argv, "abNn:")) != -1) | while ((ch = getopt(argc, argv, "abNn:")) != -1) | |||||||||
switch (ch) { /* Indent the switch. */ | switch (ch) { /* Indent the switch. */ | |||||||||
case 'a': /* Do not indent the case. */ | case 'a': /* Do not indent the case. */ | |||||||||
aflag = 1; /* Indent case body one tab. */ | aflag = 1; /* Indent case body one tab. */ | |||||||||
/* FALLTHROUGH */ | /* FALLTHROUGH */ | |||||||||
▲ Show 20 Lines • Show All 148 Lines • ▼ Show 20 Lines | ||||||||||
function(int a1, int a2, float fl, int a4, struct bar *bar) | function(int a1, int a2, float fl, int a4, struct bar *bar) | |||||||||
{ | { | |||||||||
.Ed | .Ed | |||||||||
.Pp | .Pp | |||||||||
When declaring variables in functions declare them sorted by size, | When declaring variables in functions declare them sorted by size, | |||||||||
then in alphabetical order; multiple ones per line are okay. | then in alphabetical order; multiple ones per line are okay. | |||||||||
If a line overflows reuse the type keyword. | If a line overflows reuse the type keyword. | |||||||||
Variables may be initialized where declared especially when they | Variables may be initialized where declared especially when they | |||||||||
are constant for the rest of the scope. | are constant for the rest of the scope. | |||||||||
Declarations may be placed before executable lines at the start | Declarations may be in any block, but must be placed before statements. | |||||||||
Done Inline ActionsI think the "may" refers to the "at the start of any block". i.e. what is intended is "Declarations must be placed before executable lines, and may occur at the start of any block." cperciva: I think the "may" refers to the "at the start of any block". i.e. what is intended is… | ||||||||||
Done Inline ActionsI think this is a good suggestion. pstef: I think this is a good suggestion.
I would go further and replace "executable lines" with… | ||||||||||
Done Inline ActionsI like pstef's suggestion. emaste: I like pstef's suggestion. | ||||||||||
of any block. | ||||||||||
Calls to complicated functions should be avoided when initializing variables. | Calls to complicated functions should be avoided when initializing variables. | |||||||||
.Bd -literal | .Bd -literal | |||||||||
struct foo one, *two; | struct foo one, *two; | |||||||||
struct baz *three = bar_get_baz(bar); | struct baz *three = bar_get_baz(bar); | |||||||||
double four; | double four; | |||||||||
int *five, six; | int *five, six; | |||||||||
char *seven, eight, nine, ten, eleven, twelve; | char *seven, eight, nine, ten, eleven, twelve; | |||||||||
▲ Show 20 Lines • Show All 237 Lines • Show Last 20 Lines |