Differential D25312 Diff 74442 share/man/man9/style.9

Changeset View

Standalone View

share/man/man9/style.9

Show All 19 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 January 10, 2020		.Dd July 14, 2020
.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
▲ Show 20 Lines • Show All 550 Lines • ▼ Show 20 Lines	.Bd -literal
}		}
if (val != NULL)		if (val != NULL)
val = realloc(val, newsize);		val = realloc(val, newsize);
.Ed		.Ed
.Pp		.Pp
Parts of a		Parts of a
.Ic for		.Ic for
loop may be left empty.		loop may be left empty.
Do not put declarations
inside blocks unless the routine is unusually complicated.
rgrimesUnsubmitted Not Done Inline Actions I believe we still want to say something about the fact that the preferable form is to put declarations at the top of a routing, and that these 2 exceptions exist, the for loop, and the const within scope. If we just delete the above it leaves an uncovered set of cases, some of which may be undesirable. rgrimes: I believe we still want to say something about the fact that the preferable form is to put…
rgrimesUnsubmitted Not Done Inline Actions Unaddressed? rgrimes: Unaddressed?
.Bd -literal		.Bd -literal
for (; cnt < 15; cnt++) {		for (; cnt < 15; cnt++) {
stmt1;		stmt1;
stmt2;		stmt2;
}		}
.Ed		.Ed
.Pp		.Pp
		A
		.Ic for
		rgrimesUnsubmitted Not Done Inline Actions Is it specific ONLY to for? or can I do this in a while, or other loop constructs? rgrimes: Is it specific ONLY to for? or can I do this in a while, or other loop constructs?
		rgrimesUnsubmitted Not Done Inline Actions Unaddressed? rgrimes: Unaddressed?
		cemUnsubmitted Not Done Inline Actions This only makes sense for `for` loops. cem: This only makes sense for `for` loops.
		rgrimesUnsubmitted Not Done Inline Actions Since the block scope declaration restriction has been deleted I believe this version of style would allow me to declare variables inside a while block. If that is NOT the intent it would be best to put back a reworded block restriction clause. rgrimes: Since the block scope declaration restriction has been deleted I believe this version of style…
		cemUnsubmitted Not Done Inline Actions That is intended, and has nothing to do with loops in particular. It’s permitted in any scoped block. cem: That is intended, and has nothing to do with loops in particular. It’s permitted in any scoped…
		loop may declare and initialize its counting variable.
		.Bd -literal
		for (int i = 0; i < 15; i++) {
		stmt1;
		}
		.Ed
		.Pp
Indentation is an 8 character tab.		Indentation is an 8 character tab.
Second level indents are four spaces.		Second level indents are four spaces.
If you have to wrap a long statement, put the operator at the end of the		If you have to wrap a long statement, put the operator at the end of the
line.		line.
.Bd -literal		.Bd -literal
while (cnt < 20 && this_variable_name_is_too_long &&		while (cnt < 20 && this_variable_name_is_too_long &&
ep != NULL)		ep != NULL)
z = a + really + long + statement + that + needs +		z = a + really + long + statement + that + needs +
▲ Show 20 Lines • Show All 59 Lines • ▼ Show 20 Lines
.Ed		.Ed
.Pp		.Pp
The function type should be on a line by itself		The function type should be on a line by itself
preceding the function.		preceding the function.
The opening brace of the function body should be		The opening brace of the function body should be
on a line by itself.		on a line by itself.
.Bd -literal		.Bd -literal
static char *		static char *
function(int a1, int a2, float fl, int a4)		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.
.Pp		Variables may be initialized where declared especially when they
Be careful to not obfuscate the code by initializing variables in		are constant for the rest of the scope.
the declarations.		Declarations may be placed before executable lines at the start
Use this feature only thoughtfully.		of any block.
DO NOT use function calls in initializers.		Calls to complicated functions should be avoided when initializing variables.
.Bd -literal		.Bd -literal
		cemUnsubmitted Not Done Inline Actions "constant for the rest of the scope" does not reflect real-world use of initialized-at-declaration variables in our codebase. It also isn't clear what "constant" means in this context. cem: "constant for the rest of the scope" does not reflect real-world use of initialized-at…
struct foo one, *two;		struct foo one, *two;
		cemUnsubmitted Not Done Inline Actions I don't like the added example of `struct foo one, two = bar_get_foo(bar);`. Function initializations should probably not be mixed with other declarations in a single statement. cem:* I don't like the added example of `struct foo one, *two = bar_get_foo(bar);`. Function…
double three;		struct baz *three = bar_get_baz(bar);
int *four, five;		double four;
char *six, seven, eight, nine, ten, eleven, twelve;		int *five, six;
		char *seven, eight, nine, ten, eleven, twelve;

four = myfunction();		four = my_complicated_function(a1, f1, a4);
		rgrimesUnsubmitted Not Done Inline Actions Do to all the changes on these 5 lines it makes it very hard to understand just what rule is changed. Why did myfunction, and all the other variable names get shuffled around? Why should the double be renamed to four, could you of not just used three? Since you never use four, five or six why did they need to change? rgrimes: Do to all the changes on these 5 lines it makes it very hard to understand just what rule is…
.Ed		.Ed
.Pp		.Pp
Do not declare functions inside other functions; ANSI C says that		Do not declare functions inside other functions; ANSI C says that
such declarations have file scope regardless of the nesting of the		such declarations have file scope regardless of the nesting of the
declaration.		declaration.
Hiding file declarations in what appears to be a local		Hiding file declarations in what appears to be a local
scope is undesirable and will elicit complaints from a good compiler.		scope is undesirable and will elicit complaints from a good compiler.
.Pp		.Pp
▲ Show 20 Lines • Show All 227 Lines • Show Last 20 Lines