From nobody Mon Jul 28 18:31:47 2025 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4brRrz6C4fz63M85; Mon, 28 Jul 2025 18:31:47 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R10" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4brRrz541rz3pw4; Mon, 28 Jul 2025 18:31:47 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1753727507; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=5Nw2/2Hd0nSNwWFa6RZDMipECuyi+b1f/lpUoL8ki5w=; b=kEtSUkStFYfchx3aX1gALahHflw/CPcG7nS5TPBhQ9abH0iMgzGXY2qw6thbWUrYgKd1SQ wxOaBMcYKWOmj8GCw9vFroS98fGvXBiEDSV3kdnjnuk3DTVTozLwmrvBo0IzD9bCqqUlT6 IrVulJhh5s+wCAs4+/sm204I9vYHg2PqjvuI/DhfYeQfNlza7BHtiUGO1vawpvy4GE0Zkk RXlfENSERI8jMz6/55BsqSX/jUwrQwQ3Q8RNoOK6MQ5ws4QeRhogIohci5S6gfZxWvkLI+ XjMGCw+wdVgaTuvQLXWFxNp8zMIUAxCypCNxSP30gAJ0sTn34PyTCcwR+5TKXg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1753727507; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=5Nw2/2Hd0nSNwWFa6RZDMipECuyi+b1f/lpUoL8ki5w=; b=qrQz5mwoe8zmvJCQrDQymhTiigm8PccyBMFSnLd7UeDqq1fa+LZWvxVAjoVM5tLG3EWmdT BK8cjMxueoZ/j1tm5mZsycWCOOAw8R2Nluk125Hr6NS+ehdGbYv4/8KxqWpH+D4Cz6MkwR VFHyuh+jJ7yoRgbPoSHVcRSErT1Oft03+g0a1LFCdw+qPZ8ALjYOq/nT0Fh8Dn6WSZv+f6 xbOzeSyYl6n2J8A58kzrTb5mUFtVCJr3jI9BXFr1i03hntw+yJik/hD7C2yjCbOcvAxHZe zNr9pkOE0H8l1V9HuUwV6I0xA1e9sbFbOwaNyN9sqSuXWN/br/VoEl3+R/P83A== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1753727507; a=rsa-sha256; cv=none; b=iWtUEBu4SMrEBkd2d/zd1gVhYYgejTExwL1G1xFXsESpGIbbNdRlmpSr0csEvukOqi8WFu IL/ECrI3QSXN8215Z4JSzQ/ScBcIhUVeFDrm9ij/CwkSrIDshMFx4uVrW1G/jNPOrXmlOs IrgCSLC3oIRb9eNnHagmGq5usdiuk5qi5lCpOZGpHS6y66y9PNSwFfMvX6QgQv80gMB74u kr1IXQtJi2taMO/Gu2K6yTxwwQxjB39RgX8lmng/2rjTDV83hEG5aWiCkf0GKo7UEpFJOA IbB976PbNO28/TR6/8nZJkVr2DmRfwAc3UB9dybQToZYUCNRbhET8O0P6neAIA== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4brRrz4f51zx4Q; Mon, 28 Jul 2025 18:31:47 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 56SIVli8051365; Mon, 28 Jul 2025 18:31:47 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 56SIVl39051362; Mon, 28 Jul 2025 18:31:47 GMT (envelope-from git) Date: Mon, 28 Jul 2025 18:31:47 GMT Message-Id: <202507281831.56SIVl39051362@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: John Baldwin Subject: git: 4b02ad9d5063 - main - style.9: Add a C++ section List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-main@freebsd.org Sender: owner-dev-commits-src-main@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: jhb X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 4b02ad9d506342ae47f722b830e603f5adc86b48 Auto-Submitted: auto-generated The branch main has been updated by jhb: URL: https://cgit.FreeBSD.org/src/commit/?id=4b02ad9d506342ae47f722b830e603f5adc86b48 commit 4b02ad9d506342ae47f722b830e603f5adc86b48 Author: John Baldwin AuthorDate: 2025-07-28 18:29:32 +0000 Commit: John Baldwin CommitDate: 2025-07-28 18:31:26 +0000 style.9: Add a C++ section This section adds several style guidelines for C++ in FreeBSD's base system both enumerating some differences relative to the C KNF style and addressing some unique C++ idioms not addressed by the existing KNF style. This section is not exhaustive but does include an initial set of guidelines. Reviewed by: ivy, emaste Sponsored by: Chelsio Communications Differential Revision: https://reviews.freebsd.org/D50983 --- share/man/man9/style.9 | 160 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 157 insertions(+), 3 deletions(-) diff --git a/share/man/man9/style.9 b/share/man/man9/style.9 index 484b4f144b2e..e9f17392ae0c 100644 --- a/share/man/man9/style.9 +++ b/share/man/man9/style.9 @@ -22,7 +22,7 @@ .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" -.Dd March 27, 2025 +.Dd July 28, 2025 .Dt STYLE 9 .Os .Sh NAME @@ -766,8 +766,7 @@ to any pointer type. .Pp Values in .Ic return -statements should be enclosed in parentheses where possible. -For example, parentheses cannot be used if the value is a C++ braced-init-list. +statements should be enclosed in parentheses. .Pp Use .Xr err 3 @@ -918,6 +917,161 @@ Only use the annotation for the entire if statement, rather than individual clauses. Do not add these annotations without empirical evidence of the likelihood of the branch. +.Ss C++ +KNF style was originally defined as a style for C. +C++ introduces several new idioms which do not have an existing corollary +in KNF C such as inline function definitions in classes. +C++ is also not always compatible with some KNF guidelines such as +enclosing return values in parentheses. +For C++ code, FreeBSD aims to follow broadly accepted C++ practices while +also following the general shape of KNF. +This section enumerates C++ specific guidelines that differ from KNF C. +.Pp +The preferred suffixes for C++ source files are +.Dq .cc +and +.Dq .hh . +Header files should always use a suffix, +unlike headers from the C++ standard library. +.Pp +Return values should not be enclosed in parantheses. +When converting existing C code to C++, +existing return values may remain in parantheses. +.Pp +The opening curly brace for namespace declarations should be on the first line +similar to structure and class definitions. +Nested namespaces should be declared using a single namespace declaration. +.Bd -literal +namespace foo::bar { +} +.Ed +.Pp +Member function declarations should follow the same style used for standalone +function protoypes except that a space should be used between a function's +return type and name. +.Pp +Function definitions at the top level should use a newline after the function +type similar to C function definitions. +.Pp +Nested member function definitions inside of a class, structure, or union +should not use a newline after the function type. +Instead, these should follow the style of member function declarations. +This is more common C++ style and is more compact for small methods such as +getters and setters. +.Pp +Inline functions whose body consists of a single statement may use a single +line for the function body. +Inline functions with an empty body should always use a single line. +.Bd -literal +struct widget { + int foo() { return 4; } + int bar(); +}; + +int +widget::bar() +{ + return 6; +} +.Ed +.Pp +Default and deleted methods should be declared as a single line. +.Bd -literal +class box { + ~box() = default; +}; +.Ed +.Pp +In template declarations, the +.Ic template +keyword and list of template parameters should be followed by a newline +before the templated declaration. +.Bd -literal +template +class box { + T data; +}; +.Ed +.Pp +The +.Ic & +for reference variables should be placed on the variable name rather +than the type similar to the style used with +.Ic * +for pointers. +.Bd -literal + int x; + int &xp = x; +.Ed +.Pp +Variables may be declared at any point within a function, +not just at the start of blocks. +.Pp +Standard library containers should be used in preference to +.Xr queue 3 +or +.Xr tree 3 +macros. +.Pp +.Ic nullptr +should be used instead of +.Dv NULL +or 0. +.Pp +Use standard library types for managing strings such as +.Vt std::string +and +.Vt std::string_view +rather than +.Vt "char *" +and +.Vt "const char *" . +C types may be used when interfacing with C code. +.Pp +The +.Ic auto +keyword can be used in various contexts which improve readability. +Examples include iterators, non-trivial types of ranged-for values, +and return values of obvious types, +such as +.Ic static_cast +or +.Fn std::make_unique . +Place any qualifiers before +.Ic auto , +for example: +.Ic const auto . +.Pp +Use the +.Vt std::unique_ptr +and +.Vt std::shared_ptr +smart pointers to manage the lifetime of dynamically allocated objects +instead of +.Ic new +and +.Ic delete . +Construct smart pointers with +.Fn std::make_unique +or +.Fn std::make_shared . +Do not use +.Xr malloc 3 +except when necessary to interface with C code. +.Pp +Do not import any namespaces with +.Ic using +at global scope in header files. +Namespaces other than the +.Ic std +namespace (for example, +.Ic std::literals ) +may be imported in source files and in function scope in header files. +.Pp +Define type aliases using +.Ic using +instead of +.Ic typedef . .Sh FILES .Bl -tag -width indent .It Pa /usr/src/tools/build/checkstyle9.pl