Lines Matching +full:out +full:- +full:functions
12 First off, I'd suggest printing out a copy of the GNU coding standards,
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
38 benefit of warning you when you're nesting your functions too deep.
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
151 However, there is one special case, namely functions: they have the
154 .. code-block:: c
162 is ... well ... inconsistent, but all right-thinking people know that
163 (a) K&R are **right** and (b) K&R are right. Besides, functions are
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:: c
216 .. code-block:: c
227 .. code-block:: c
238 function-versus-keyword usage. Use a space after (most) keywords. The
240 somewhat like functions (and are usually used with parentheses in Linux,
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.
336 See chapter 6 (Functions).
360 -----------
365 .. code-block:: c
373 .. code-block:: c
386 the proper accessor functions.
390 Opaqueness and ``accessor functions`` are not good in themselves.
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
443 6) Functions
444 ------------
446 Functions should be short and sweet, and do just one thing. They should
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
459 maximum limits all the more closely. Use helper functions with
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
471 In source files, separate functions with one blank line. If the function is
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``)
526 7) Centralized exiting of functions
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.
639 ---------------------------
641 That's OK, we all do. You've probably been told by your long-time Unix
645 typing - an infinite number of monkeys typing into GNU emacs would never
651 .. code-block:: elisp
653 (defun c-lineup-arglist-tabs-only (ignored)
655 (let* ((anchor (c-langelem-pos c-syntactic-element))
656 (column (c-langelem-2nd-pos c-syntactic-element))
657 (offset (- (1+ column) anchor))
658 (steps (floor offset c-basic-offset)))
660 c-basic-offset)))
662 (dir-locals-set-class-variables
663 'linux-kernel
664 '((c-mode . (
665 (c-basic-offset . 8)
666 (c-label-minimum-indentation . 0)
667 (c-offsets-alist . (
668 (arglist-close . c-lineup-arglist-tabs-only)
669 (arglist-cont-nonempty .
670 (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
671 (arglist-intro . +)
672 (brace-list-intro . +)
673 (c . c-lineup-C-comments)
674 (case-label . 0)
675 (comment-intro . c-lineup-comment)
676 (cpp-define-intro . +)
677 (cpp-macro . -1000)
678 (cpp-macro-cont . +)
679 (defun-block-intro . +)
680 (else-clause . 0)
681 (func-decl-cont . +)
683 (inher-cont . c-lineup-multi-inher)
684 (knr-argdecl-intro . 0)
685 (label . -1000)
687 (statement-block-intro . +)
688 (statement-case-intro . +)
689 (statement-cont . +)
692 (indent-tabs-mode . t)
693 (show-trailing-whitespace . t)
696 (dir-locals-set-directory-class
697 (expand-file-name "~/src/linux-trees")
698 'linux-kernel)
701 files below ``~/src/linux-trees``.
706 Now, again, GNU indent has the same brain-dead settings that GNU emacs
711 options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use
715 re-formatting you may want to take a look at the man page. But
718 Note that you can also use the ``clang-format`` tool to help you with
719 these rules, to quickly re-format parts of your code automatically,
723 See the file :ref:`Documentation/dev-tools/clang-format.rst <clangformat>`
732 -------------------------------
745 logging of avc messages output). Does not do system-call
757 Documentation/kbuild/kconfig-language.rst.
761 -------------------
763 Data structures that have visibility outside the single-threaded
770 users to have access to the data structure in parallel - and not having
784 Examples of this kind of ``multi-level-reference-counting`` can be found in
793 -------------------------
797 .. code-block:: c
803 CAPITALIZED macro names are appreciated but macros resembling functions
806 Generally, inline functions are preferable to macros resembling functions.
808 Macros with multiple statements should be enclosed in a do - while block:
810 .. code-block:: c
818 Function-like macros with unused parameters should be replaced by static
819 inline functions to avoid the issue of unused variables:
821 .. code-block:: c
829 Inline functions address the issue of "expression with side effects
830 evaluated more than once", circumvent unused-variable problems, and
833 .. code-block:: c
837 * inline functions
845 .. code-block:: c
850 return -EBUGGERED; \
858 .. code-block:: c
865 3) macros with arguments that are used as l-values: FOO(x) = y; will
872 .. code-block:: c
878 functions:
880 .. code-block:: c
889 ret is a common name for a local variable - __foo_ret is less likely
897 ----------------------------
918 debug message printing is handled differently than printing other non-debug
919 messages. While the other pr_XXX() functions print unconditionally,
920 pr_debug() does not; it is compiled out by default, unless either DEBUG is
925 Many subsystems have Kconfig debug options to turn on -DDEBUG in the
928 already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
933 ---------------------
938 about them. :ref:`Documentation/core-api/memory-allocation.rst
943 .. code-block:: c
947 The alternative form where struct name is spelled out hurts readability and
957 .. code-block:: c
963 .. code-block:: c
970 These generic allocation functions all emit a stack dump on failure when used
975 ----------------------
987 A reasonable rule of thumb is to not put inline at functions that have more
994 Often people argue that adding inline to functions that are static and used
1003 ------------------------------------
1005 Functions can return values of many different kinds, and one of the
1007 failed. Such a value can be represented as an error-code integer
1008 (-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure,
1009 non-zero = success).
1012 difficult-to-find bugs. If the C language included a strong distinction
1018 the function should return an error-code integer. If the name
1022 for success or -EBUSY for failure. In the same way, ``PCI device present`` is
1026 All EXPORTed functions must respect this convention, and so should all
1027 public functions. Private (static) functions need not, but it is
1030 Functions whose return value is the actual result of a computation, rather
1032 this rule. Generally they indicate failure by returning some out-of-range
1033 result. Typical examples would be functions that return pointers; they use
1038 --------------
1062 readable alternative if the call-sites have naked true/false constants.
1067 18) Don't re-invent the kernel macros
1068 -------------------------------------
1075 .. code-block:: c
1081 .. code-block:: c
1083 #define sizeof_field(t, f) (sizeof(((t*)0)->f))
1091 ------------------------------------
1097 .. code-block:: c
1099 -*- mode: c -*-
1103 .. code-block:: c
1107 compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
1113 .. code-block:: c
1125 -------------------
1127 In architecture-specific code, you may need to use inline assembly to interface
1132 Consider writing simple helper functions that wrap common bits of inline
1136 Large, non-trivial assembly functions should go in .S files, with corresponding
1138 functions should use ``asmlinkage``.
1149 .. code-block:: c
1157 ---------------------------
1161 use such conditionals in a header file defining functions for use in those .c
1162 files, providing no-op stub versions in the #else case, and then call those
1163 functions unconditionally from .c files. The compiler will avoid generating
1167 Prefer to compile out entire functions, rather than portions of functions or
1169 out part or all of the expression into a separate helper function and apply the
1181 .. code-block:: c
1187 The compiler will constant-fold the conditional away, and include or exclude
1194 At the end of any non-trivial #if or #ifdef block (more than a few lines),
1198 .. code-block:: c
1206 ---------------------------
1215 panic() is, for example, acceptable when running out of memory during boot and
1242 WARN*() is intended for unexpected, this-should-never-happen situations.
1244 during normal operation. These are not pre- or post-condition asserts, for
1261 Use BUILD_BUG_ON() for compile-time assertions
1265 compile-time assertion that has no effect at runtime.
1268 ----------------------
1273 ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
1277 Addison-Wesley, Inc., 1999.
1278 ISBN 0-201-61586-X.
1280 GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
1284 language C, URL: http://www.open-std.org/JTC1/SC22/WG14/