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 October 28, 2020 | .Dd February 2, 2022 | ||||
.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 | ||||
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). | ||||
* | * | ||||
* @(#)style 1.14 (Berkeley) 4/28/95 | * @(#)style 1.14 (Berkeley) 4/28/95 | ||||
* $FreeBSD$ | |||||
kib: But do you plan to merge this text to stable/12? | |||||
Done Inline ActionsNo. I generally don't MFC style(9) changes. This won't be merged to 12 imp: No. I generally don't MFC style(9) changes. This won't be merged to 12 | |||||
*/ | */ | ||||
/* | /* | ||||
* VERY important single-line comments look like this. | * VERY important single-line comments look like this. | ||||
*/ | */ | ||||
/* Most single-line comments look like this. */ | /* Most single-line comments look like this. */ | ||||
▲ Show 20 Lines • Show All 47 Lines • ▼ Show 20 Lines | |||||
.Dq Li "Copyright" , | .Dq Li "Copyright" , | ||||
new copyright assertions should be added last. | new copyright assertions should be added last. | ||||
New | New | ||||
.Dq Li "Copyright" | .Dq Li "Copyright" | ||||
lines should only be added when making substantial changes to the file, | lines should only be added when making substantial changes to the file, | ||||
not for trivial changes. | not for trivial changes. | ||||
.Pp | .Pp | ||||
After any copyright and license comment, there is a blank line. | After any copyright and license comment, there is a blank line. | ||||
If your code needs to be merged into stable/12 or earlier, it | New code should only include | ||||
Not Done Inline ActionsI think that 'generally' is unnecessary wordy. I'd drop it. 0mp: I think that 'generally' is unnecessary wordy. I'd drop it. | |||||
needs to have the | |||||
.Li $\&FreeBSD$ | .Li $\&FreeBSD$ | ||||
tag. | or | ||||
Otherwise, this tag should be omitted in new code. | .Li __FBSDID("$\&FreeBSD$"); | ||||
when it will be merged into stable/12. | |||||
Not Done Inline ActionsCode which will definitely be merged into stable/12 should include the .Li $\&FreeBSD$ tag here. Otherwise, that tag should be omitted. (Or maybe may include instead of should include?) rpokala: ```
Code which will definitely be merged into stable/12 should include the
.Li $\&FreeBSD$
tag… | |||||
Not Done Inline ActionsI agree, the word 'omit' means that the tag have to be included first. May be better say 'No VCS tags should be added', if anything. kib: I agree, the word 'omit' means that the tag have to be included first. May be better say 'No… | |||||
Not Done Inline Actions+1 0mp: +1 | |||||
Done Inline Actions"New code should only include a maybe. 'may' is definitely the wrong word here, it implies too much discretion. You should do this if you plan on MFCing. And that's the only time you should do this. Not quite a 'must' in RFC-speak, though, imho, which gives no discretion. imp: "New code should only include a
.Li $\&FreeBSD$
tag when it will be merged into stable/12."… | |||||
cemUnsubmitted Not Done Inline ActionsI’d use “if” instead of “when.” cem: I’d use “if” instead of “when.” | |||||
rpokalaUnsubmitted Not Done Inline Actions"when" => "if and when" ? rpokala: "when" => "if and when" ? | |||||
Legacy code will have the tag removed in the future. | Legacy code will have the tag removed in the future. | ||||
For non C/C++ language source files, | |||||
.Li $\&FreeBSD$ | |||||
is next, if applicable. | |||||
Non-C/C++ source files follow the example above, while C/C++ source files | Non-C/C++ source files follow the example above, while C/C++ source files | ||||
follow the one below. | follow the one below. | ||||
Version control system ID tags should only exist once in a file | Version control system ID tags should only exist once in a file | ||||
(unlike in this one). | (unlike in this one). | ||||
All VCS (version control system) revision identification in files obtained | All VCS (version control system) revision identification in files obtained | ||||
from elsewhere should be maintained, including, where applicable, multiple IDs | from elsewhere should be maintained, including, where applicable, multiple IDs | ||||
showing a file's history. | showing a file's history. | ||||
In general, do not edit foreign IDs or their infrastructure. | In general, do not edit foreign IDs or their infrastructure. | ||||
Unless otherwise wrapped (such as | Unless otherwise wrapped (such as | ||||
.Dq Li "#if defined(LIBC_SCCS)" ) , | .Dq Li "#if defined(LIBC_SCCS)" ) , | ||||
pauamma_gundo.comUnsubmitted Not Done Inline ActionsWhile changing this file: maybe change LIB_SCCS to a more recent example? (Did FreeBSD ever use SCCS?) pauamma_gundo.com: While changing this file: maybe change LIB_SCCS to a more recent example? (Did FreeBSD ever use… | |||||
impAuthorUnsubmitted Done Inline ActionsI'd rather not change this now.... imp: I'd rather not change this now....
FreeBSD had this advise because CSRG used SCCS and we… | |||||
enclose both in | enclose both in | ||||
.Dq Li "#if 0 ... #endif" | .Dq Li "#if 0 ... #endif" | ||||
to hide any uncompilable bits | to hide any uncompilable bits | ||||
and to keep the IDs out of object files. | and to keep the IDs out of object files. | ||||
Only add | Only add | ||||
.Dq Li "From: " | .Dq Li "From: " | ||||
in front of foreign VCS IDs if the file is renamed. | in front of foreign VCS IDs if the file is renamed. | ||||
Add | Add | ||||
.Dq Li "From: " | .Dq Li "From: " | ||||
and FreeBSD git hash with full path name if the file was derived | and FreeBSD git hash with full path name if the file was derived | ||||
from another FreeBSD file and include relevant copyright info | from another FreeBSD file and include relevant copyright info | ||||
from the original file. | from the original file. | ||||
.Bd -literal | .Bd -literal | ||||
/* From: @(#)style 1.14 (Berkeley) 4/28/95 */ | /* From: @(#)style 1.14 (Berkeley) 4/28/95 */ | ||||
#include <sys/cdefs.h> | |||||
__FBSDID("$FreeBSD$"); | |||||
.Ed | .Ed | ||||
.Pp | .Pp | ||||
Leave one blank line before the header files. | Leave one blank line before the header files. | ||||
.Pp | .Pp | ||||
Kernel include files | Kernel include files | ||||
.Pa ( sys/*.h ) | .Pa ( sys/*.h ) | ||||
come first. | come first. | ||||
If | If | ||||
▲ Show 20 Lines • Show All 799 Lines • Show Last 20 Lines |
But do you plan to merge this text to stable/12?