linux.git/Documentation/process/coding-style.rst, branch v6.18.21 Clone of https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git docs: process: discourage pointless boilerplate kdoc 2025-06-21T20:14:33+00:00 Jakub Kicinski kuba@kernel.org 2025-06-14T20:42:57+00:00 e5880f95a97928308845dc97fdd239605e06e501 It appears that folks "less versed in kernel coding" think that its good style to document every function, even if they have no useful information to pass to the future readers of the code. This used to be just a waste of space, but with increased kdoc format linting it's also a burden when refactoring the code. Signed-off-by: Jakub Kicinski <kuba@kernel.org> Reviewed-by: Joe Damato <joe@dama.to> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250614204258.61449-1-kuba@kernel.org 
It appears that folks "less versed in kernel coding" think that its
good style to document every function, even if they have no useful
information to pass to the future readers of the code. This used
to be just a waste of space, but with increased kdoc format linting
it's also a burden when refactoring the code.

Signed-off-by: Jakub Kicinski <kuba@kernel.org>
Reviewed-by: Joe Damato <joe@dama.to>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250614204258.61449-1-kuba@kernel.org
docs/process: fix typos 2024-09-10T21:16:28+00:00 Andrew Kreimer algonell@gmail.com 2024-09-07T12:21:39+00:00 c5d436f05a3f45053cfc820ae140899b916c6e00 Fix typos in documentation. Signed-off-by: Andrew Kreimer <algonell@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20240907122534.15998-1-algonell@gmail.com> 
Fix typos in documentation.

Signed-off-by: Andrew Kreimer <algonell@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20240907122534.15998-1-algonell@gmail.com>
net: drop special comment style 2024-08-23T09:21:02+00:00 Johannes Berg johannes.berg@intel.com 2024-08-19T09:09:43+00:00 82b8000c28b56b014ce52a1f1581bef4af148681 As we discussed in the room at netdevconf earlier this week, drop the requirement for special comment style for netdev. For checkpatch, the general check accepts both right now, so simply drop the special request there as well. Acked-by: Stephen Hemminger <stephen@networkplumber.org> Signed-off-by: Johannes Berg <johannes.berg@intel.com> Acked-by: Jakub Kicinski <kuba@kernel.org> Signed-off-by: David S. Miller <davem@davemloft.net> 
As we discussed in the room at netdevconf earlier this week,
drop the requirement for special comment style for netdev.

For checkpatch, the general check accepts both right now, so
simply drop the special request there as well.

Acked-by: Stephen Hemminger <stephen@networkplumber.org>
Signed-off-by: Johannes Berg <johannes.berg@intel.com>
Acked-by: Jakub Kicinski <kuba@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
Docs: Move clang-format from process/ to dev-tools/ 2024-06-26T22:36:00+00:00 SeongJae Park sj@kernel.org 2024-06-24T18:53:09+00:00 e3b10a02ca2fe1e27ee008e9fcd8cf7076f7f776 'clang-format' is on 'Other material' section of 'process/index', but it may fit more under 'dev-tools/' directory. Move it. Signed-off-by: SeongJae Park <sj@kernel.org> Acked-by: Miguel Ojeda <ojeda@kernel.org> Acked-by: Federico Vaga <federico.vaga@vaga.pv.it> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240624185312.94537-5-sj@kernel.org 
'clang-format' is on 'Other material' section of 'process/index', but it
may fit more under 'dev-tools/' directory.  Move it.

Signed-off-by: SeongJae Park <sj@kernel.org>
Acked-by: Miguel Ojeda <ojeda@kernel.org>
Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240624185312.94537-5-sj@kernel.org
Documentation: coding-style: ask function-like macros to evaluate parameters 2024-05-11T22:51:44+00:00 Barry Song v-songbaohua@oppo.com 2024-05-07T03:27:56+00:00 6813216bbdba18e182759d949589be95ebef290f Patch series "codingstyle: avoid unused parameters for a function-like macro", v7. A function-like macro could result in build warnings such as "unused variable." This patchset updates the guidance to recommend always using a static inline function instead and also provides checkpatch support for this new rule. This patch (of 2): Recent commit 77292bb8ca69c80 ("crypto: scomp - remove memcpy if sg_nents is 1 and pages are lowmem") leads to warnings on xtensa and loongarch, In file included from crypto/scompress.c:12: include/crypto/scatterwalk.h: In function 'scatterwalk_pagedone': include/crypto/scatterwalk.h:76:30: warning: variable 'page' set but not used [-Wunused-but-set-variable] 76 | struct page *page; | ^~~~ crypto/scompress.c: In function 'scomp_acomp_comp_decomp': >> crypto/scompress.c:174:38: warning: unused variable 'dst_page' [-Wunused-variable] 174 | struct page *dst_page = sg_page(req->dst); | The reason is that flush_dcache_page() is implemented as a noop macro on these platforms as below, #define flush_dcache_page(page) do { } while (0) The driver code, for itself, seems be quite innocent and placing maybe_unused seems pointless, struct page *dst_page = sg_page(req->dst); for (i = 0; i < nr_pages; i++) flush_dcache_page(dst_page + i); And it should be independent of architectural implementation differences. Let's provide guidance on coding style for requesting parameter evaluation or proposing the migration to a static inline function. Link: https://lkml.kernel.org/r/20240507032757.146386-1-21cnbao@gmail.com Link: https://lkml.kernel.org/r/20240507032757.146386-2-21cnbao@gmail.com Signed-off-by: Barry Song <v-songbaohua@oppo.com> Suggested-by: Max Filippov <jcmvbkbc@gmail.com> Reviewed-by: Mark Brown <broonie@kernel.org> Acked-by: Joe Perches <joe@perches.com> Cc: Chris Zankel <chris@zankel.net> Cc: Huacai Chen <chenhuacai@loongson.cn> Cc: Herbert Xu <herbert@gondor.apana.org.au> Cc: Guenter Roeck <linux@roeck-us.net> Cc: Stephen Rothwell <sfr@canb.auug.org.au> Cc: Andy Whitcroft <apw@canonical.com> Cc: Dwaipayan Ray <dwaipayanray1@gmail.com> Cc: Joe Perches <joe@perches.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Lukas Bulwahn <lukas.bulwahn@gmail.com> Cc: Xining Xu <mac.xxn@outlook.com> Cc: Charlemagne Lasse <charlemagnelasse@gmail.com> Cc: Jeff Johnson <quic_jjohnson@quicinc.com> Signed-off-by: Andrew Morton <akpm@linux-foundation.org> 
Patch series "codingstyle: avoid unused parameters for a function-like
macro", v7.

A function-like macro could result in build warnings such as "unused
variable." This patchset updates the guidance to recommend always using a
static inline function instead and also provides checkpatch support for
this new rule.


This patch (of 2):

Recent commit 77292bb8ca69c80 ("crypto: scomp - remove memcpy if
sg_nents is 1 and pages are lowmem") leads to warnings on xtensa
and loongarch,
   In file included from crypto/scompress.c:12:
   include/crypto/scatterwalk.h: In function 'scatterwalk_pagedone':
   include/crypto/scatterwalk.h:76:30: warning: variable 'page' set but not used [-Wunused-but-set-variable]
      76 |                 struct page *page;
         |                              ^~~~
   crypto/scompress.c: In function 'scomp_acomp_comp_decomp':
>> crypto/scompress.c:174:38: warning: unused variable 'dst_page' [-Wunused-variable]
     174 |                         struct page *dst_page = sg_page(req->dst);
         |

The reason is that flush_dcache_page() is implemented as a noop
macro on these platforms as below,

 #define flush_dcache_page(page) do { } while (0)

The driver code, for itself, seems be quite innocent and placing
maybe_unused seems pointless,

 struct page *dst_page = sg_page(req->dst);

 for (i = 0; i < nr_pages; i++)
 	flush_dcache_page(dst_page + i);

And it should be independent of architectural implementation
differences.

Let's provide guidance on coding style for requesting parameter
evaluation or proposing the migration to a static inline
function.

Link: https://lkml.kernel.org/r/20240507032757.146386-1-21cnbao@gmail.com
Link: https://lkml.kernel.org/r/20240507032757.146386-2-21cnbao@gmail.com
Signed-off-by: Barry Song <v-songbaohua@oppo.com>
Suggested-by: Max Filippov <jcmvbkbc@gmail.com>
Reviewed-by: Mark Brown <broonie@kernel.org>
Acked-by: Joe Perches <joe@perches.com>
Cc: Chris Zankel <chris@zankel.net>
Cc: Huacai Chen <chenhuacai@loongson.cn>
Cc: Herbert Xu <herbert@gondor.apana.org.au>
Cc: Guenter Roeck <linux@roeck-us.net>
Cc: Stephen Rothwell <sfr@canb.auug.org.au>
Cc: Andy Whitcroft <apw@canonical.com>
Cc: Dwaipayan Ray <dwaipayanray1@gmail.com>
Cc: Joe Perches <joe@perches.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Cc: Xining Xu <mac.xxn@outlook.com>
Cc: Charlemagne Lasse <charlemagnelasse@gmail.com>
Cc: Jeff Johnson <quic_jjohnson@quicinc.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Documentation: coding-style: Update syntax highlighting for code-blocks 2024-02-05T17:21:50+00:00 Thorsten Blum thorsten.blum@toblux.com 2024-02-03T22:39:26+00:00 185ea7676ef3220de1ee90f288df3601f83afda0 Use c and elisp instead of none in code-blocks Signed-off-by: Thorsten Blum <thorsten.blum@toblux.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240203223926.5077-1-thorsten.blum@toblux.com 
Use c and elisp instead of none in code-blocks

Signed-off-by: Thorsten Blum <thorsten.blum@toblux.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240203223926.5077-1-thorsten.blum@toblux.com
Documentation: coding-style: Fix indentation in code-blocks 2024-02-05T17:15:31+00:00 Thorsten Blum thorsten.blum@toblux.com 2024-02-02T23:13:16+00:00 932be49b71e7a67a288b29e78c45bd095a4be704 - Remove spaces in C code-blocks to align error labels consistently - Replace tab characters with spaces in emacs-lisp code blocks Signed-off-by: Thorsten Blum <thorsten.blum@toblux.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240202231316.7606-1-thorsten.blum@toblux.com 
- Remove spaces in C code-blocks to align error labels consistently
- Replace tab characters with spaces in emacs-lisp code blocks

Signed-off-by: Thorsten Blum <thorsten.blum@toblux.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240202231316.7606-1-thorsten.blum@toblux.com
coding-style: Add guidance to prefer dev_dbg 2024-01-30T21:03:33+00:00 Abhishek Pandit-Subedi abhishekpandit@chromium.org 2024-01-26T00:53:11+00:00 5c7944ca7b13978744ec83e131aef9255fdbabbe During review, it was suggested that drivers only emit messages when something is wrong or it is a debug message. Document this as a formal recommendation. https://lore.kernel.org/linux-usb/2024012525-alienate-frown-916b@gregkh/ Signed-off-by: Abhishek Pandit-Subedi <abhishekpandit@chromium.org> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20240125165311.1.I8d9c88e747e233917e527c7dad1feb8a18f070e2@changeid 
During review, it was suggested that drivers only emit messages when
something is wrong or it is a debug message. Document this as a formal
recommendation.

https://lore.kernel.org/linux-usb/2024012525-alienate-frown-916b@gregkh/

Signed-off-by: Abhishek Pandit-Subedi <abhishekpandit@chromium.org>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240125165311.1.I8d9c88e747e233917e527c7dad1feb8a18f070e2@changeid
Add .editorconfig file for basic formatting 2023-12-28T07:22:47+00:00 Íñigo Huguet ihuguet@redhat.com 2023-06-01T07:53:33+00:00 5a602de99797bddc9dd7f73592281a507196f69d EditorConfig is a specification to define the most basic code formatting stuff, and it's supported by many editors and IDEs, either directly or via plugins, including VSCode/VSCodium, Vim, emacs and more. It allows to define formatting style related to indentation, charset, end of lines and trailing whitespaces. It also allows to apply different formats for different files based on wildcards, so for example it is possible to apply different configs to *.{c,h}, *.py and *.rs. In linux project, defining a .editorconfig might help to those people that work on different projects with different indentation styles, so they cannot define a global style. Now they will directly see the correct indentation on every fresh clone of the project. See https://editorconfig.org Co-developed-by: Danny Lin <danny@kdrag0n.dev> Signed-off-by: Danny Lin <danny@kdrag0n.dev> Signed-off-by: Íñigo Huguet <ihuguet@redhat.com> Acked-by: Mickaël Salaün <mic@digikod.net> Reviewed-by: Vincent Mailhol <mailhol.vincent@wanadoo.fr> Tested-by: Vincent Mailhol <mailhol.vincent@wanadoo.fr> Signed-off-by: Masahiro Yamada <masahiroy@kernel.org> 
EditorConfig is a specification to define the most basic code formatting
stuff, and it's supported by many editors and IDEs, either directly or
via plugins, including VSCode/VSCodium, Vim, emacs and more.

It allows to define formatting style related to indentation, charset,
end of lines and trailing whitespaces. It also allows to apply different
formats for different files based on wildcards, so for example it is
possible to apply different configs to *.{c,h}, *.py and *.rs.

In linux project, defining a .editorconfig might help to those people
that work on different projects with different indentation styles, so
they cannot define a global style. Now they will directly see the
correct indentation on every fresh clone of the project.

See https://editorconfig.org

Co-developed-by: Danny Lin <danny@kdrag0n.dev>
Signed-off-by: Danny Lin <danny@kdrag0n.dev>
Signed-off-by: Íñigo Huguet <ihuguet@redhat.com>
Acked-by: Mickaël Salaün <mic@digikod.net>
Reviewed-by: Vincent Mailhol <mailhol.vincent@wanadoo.fr>
Tested-by: Vincent Mailhol <mailhol.vincent@wanadoo.fr>
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
coding-style: fix title of Greg K-H's talk 2023-03-23T18:04:08+00:00 Jakub Wilk jwilk@jwilk.net 2023-03-22T21:53:11+00:00 775a445d9a638d8950b1831b605ae6a92a468d7e The talk title was inadvertently mangled in 8c27ceff3604 ("docs: fix locations of several documents that got moved"). Signed-off-by: Jakub Wilk <jwilk@jwilk.net> Link: https://lore.kernel.org/r/20230322215311.6579-1-jwilk@jwilk.net Signed-off-by: Jonathan Corbet <corbet@lwn.net> 
The talk title was inadvertently mangled in 8c27ceff3604 ("docs: fix
locations of several documents that got moved").

Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Link: https://lore.kernel.org/r/20230322215311.6579-1-jwilk@jwilk.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>