Lines Matching +full:non +full:- +full:descriptive
19 --------------
31 Now, some people will claim that having 8-character indentations makes
33 80-character terminal screen. The answer to that is that if you need
37 In short, 8-char indents make things easier to read, and have the added
43 instead of ``double-indenting`` the ``case`` labels. E.g.:
45 .. code-block:: c
67 .. code-block:: c
74 .. code-block:: c
81 .. code-block:: c
99 ----------------------------------
116 However, never break user-visible strings such as printk messages because
121 ----------------------------
129 .. code-block:: c
135 This applies to all non-function statement blocks (if, switch, for,
138 .. code-block:: c
154 .. code-block:: c
162 is ... well ... inconsistent, but all right-thinking people know that
168 ie a ``while`` in a do-statement or an ``else`` in an if-statement, like
171 .. code-block:: c
174 body of do-loop
179 .. code-block:: c
191 Also, note that this brace-placement also minimizes the number of empty
193 supply of new-lines on your screen is not a renewable resource (think
194 25-line terminal screens here), you have more empty lines to put
199 .. code-block:: c
206 .. code-block:: none
216 .. code-block:: c
227 .. code-block:: c
238 function-versus-keyword usage. Use a space after (most) keywords. The
250 .. code-block:: c
258 .. code-block:: c
267 .. code-block:: c
277 = + - < > * / % | & ^ <= >= == != ? :
281 & * + - ~ ! sizeof typeof alignof __attribute__ defined
285 ++ --
289 ++ --
291 and no space around the ``.`` and ``->`` structure member operators.
307 ---------
310 Unlike Modula-2 and Pascal programmers, C programmers do not use cute
315 HOWEVER, while mixed-case names are frowned upon, descriptive names for
320 have descriptive names, as do global functions. If you have a function
324 Encoding the type of a function into the name (so-called Hungarian
325 notation) is asinine - the compiler knows the types anyway and can check
330 Calling it ``loop_counter`` is non-productive, if there is no chance of it
331 being mis-understood. Similarly, ``tmp`` can be just about any type of
335 problem, which is called the function-growth-hormone-imbalance syndrome.
360 -----------
365 .. code-block:: c
373 .. code-block:: c
402 Again - there needs to be a **reason** for this. If something is
412 type-checking.
421 Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their
423 permitted -- although they are not mandatory in new code of your
444 ------------
453 case-statement, where you have to do lots of small things for a lot of
457 less-than-gifted first-year high-school student might not even
460 descriptive names (you can ask the compiler to in-line them if you think
461 it's performance-critical, and it will probably do a better job of it
465 shouldn't exceed 5-10, or you're doing something wrong. Re-think the
475 .. code-block:: c
494 <https://lore.kernel.org/mm-commits/CAHk-=wiOCLRny5aifWNhr621kYrJwhfURsa0vFPeUEm8mF0ufg@mail.gmail.…
502 - storage class (below, ``static __always_inline``, noting that ``__always_inline``
504 - storage class attributes (here, ``__init`` -- i.e. section declarations, but also
506 - return type (here, ``void *``)
507 - return type attributes (here, ``__must_check``)
508 - function name (here, ``action``)
509 - function parameters (here, ``(enum magic value, size_t size, u8 count, char *fmt, ...)``,
511 - function parameter attributes (here, ``__printf(4, 5)``)
512 - function behavior attributes (here, ``__malloc``)
527 -----------------------------------
538 Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to
544 - unconditional statements are easier to understand and follow
545 - nesting is reduced
546 - errors by not updating individual exit points when making
548 - saves the compiler work to optimize redundant code away ;)
550 .. code-block:: c
559 return -ENOMEM;
576 .. code-block:: c
579 kfree(foo->bar);
587 .. code-block:: c
590 kfree(foo->bar);
599 -------------
601 Comments are good, but there is also a danger of over-commenting. NEVER
615 When commenting the kernel API functions, please use the kernel-doc format.
616 See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and
617 ``scripts/kernel-doc`` for details.
619 The preferred style for long (multi-line) comments is:
621 .. code-block:: c
624 * This is the preferred style for multi-line
629 * with beginning and ending almost-blank lines.
632 For files in net/ and drivers/net/ the preferred style for long (multi-line)
635 .. code-block:: c
641 * but there is no initial almost-blank line.
651 ---------------------------
653 That's OK, we all do. You've probably been told by your long-time Unix
657 typing - an infinite number of monkeys typing into GNU emacs would never
663 .. code-block:: none
665 (defun c-lineup-arglist-tabs-only (ignored)
667 (let* ((anchor (c-langelem-pos c-syntactic-element))
668 (column (c-langelem-2nd-pos c-syntactic-element))
669 (offset (- (1+ column) anchor))
670 (steps (floor offset c-basic-offset)))
672 c-basic-offset)))
674 (dir-locals-set-class-variables
675 'linux-kernel
676 '((c-mode . (
677 (c-basic-offset . 8)
678 (c-label-minimum-indentation . 0)
679 (c-offsets-alist . (
680 (arglist-close . c-lineup-arglist-tabs-only)
681 (arglist-cont-nonempty .
682 (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
683 (arglist-intro . +)
684 (brace-list-intro . +)
685 (c . c-lineup-C-comments)
686 (case-label . 0)
687 (comment-intro . c-lineup-comment)
688 (cpp-define-intro . +)
689 (cpp-macro . -1000)
690 (cpp-macro-cont . +)
691 (defun-block-intro . +)
692 (else-clause . 0)
693 (func-decl-cont . +)
695 (inher-cont . c-lineup-multi-inher)
696 (knr-argdecl-intro . 0)
697 (label . -1000)
699 (statement-block-intro . +)
700 (statement-case-intro . +)
701 (statement-cont . +)
704 (indent-tabs-mode . t)
705 (show-trailing-whitespace . t)
708 (dir-locals-set-directory-class
709 (expand-file-name "~/src/linux-trees")
710 'linux-kernel)
713 files below ``~/src/linux-trees``.
718 Now, again, GNU indent has the same brain-dead settings that GNU emacs
723 options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use
727 re-formatting you may want to take a look at the man page. But
730 Note that you can also use the ``clang-format`` tool to help you with
731 these rules, to quickly re-format parts of your code automatically,
735 See the file :ref:`Documentation/process/clang-format.rst <clangformat>`
740 -------------------------------
753 logging of avc messages output). Does not do system-call
765 Documentation/kbuild/kconfig-language.rst.
769 -------------------
771 Data structures that have visibility outside the single-threaded
778 users to have access to the data structure in parallel - and not having
792 Examples of this kind of ``multi-level-reference-counting`` can be found in
801 -------------------------
805 .. code-block:: c
816 Macros with multiple statements should be enclosed in a do - while block:
818 .. code-block:: c
830 .. code-block:: c
835 return -EBUGGERED; \
843 .. code-block:: c
850 3) macros with arguments that are used as l-values: FOO(x) = y; will
857 .. code-block:: c
865 .. code-block:: c
874 ret is a common name for a local variable - __foo_ret is less likely
882 ----------------------------
902 debug message printing is handled differently than printing other non-debug
909 Many subsystems have Kconfig debug options to turn on -DDEBUG in the
912 already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
917 ---------------------
922 about them. :ref:`Documentation/core-api/memory-allocation.rst
927 .. code-block:: c
941 .. code-block:: c
947 .. code-block:: c
959 ----------------------
987 ------------------------------------
991 failed. Such a value can be represented as an error-code integer
992 (-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure,
993 non-zero = success).
996 difficult-to-find bugs. If the C language included a strong distinction
1002 the function should return an error-code integer. If the name
1006 for success or -EBUSY for failure. In the same way, ``PCI device present`` is
1016 this rule. Generally they indicate failure by returning some out-of-range
1022 --------------
1046 readable alternative if the call-sites have naked true/false constants.
1051 18) Don't re-invent the kernel macros
1052 -------------------------------------
1059 .. code-block:: c
1065 .. code-block:: c
1067 #define sizeof_field(t, f) (sizeof(((t*)0)->f))
1075 ------------------------------------
1081 .. code-block:: c
1083 -*- mode: c -*-
1087 .. code-block:: c
1091 compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
1097 .. code-block:: c
1109 -------------------
1111 In architecture-specific code, you may need to use inline assembly to interface
1120 Large, non-trivial assembly functions should go in .S files, with corresponding
1133 .. code-block:: c
1141 ---------------------------
1146 files, providing no-op stub versions in the #else case, and then call those
1165 .. code-block:: c
1171 The compiler will constant-fold the conditional away, and include or exclude
1178 At the end of any non-trivial #if or #ifdef block (more than a few lines),
1182 .. code-block:: c
1190 ---------------------------
1226 WARN*() is intended for unexpected, this-should-never-happen situations.
1228 during normal operation. These are not pre- or post-condition asserts, for
1245 Use BUILD_BUG_ON() for compile-time assertions
1249 compile-time assertion that has no effect at runtime.
1252 ----------------------
1257 ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
1261 Addison-Wesley, Inc., 1999.
1262 ISBN 0-201-61586-X.
1264 GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
1268 language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
1270 Kernel :ref:`process/coding-style.rst <codingstyle>`, by greg@kroah.com at OLS 2002: