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
82 ----------------------------------
94 with a long argument list. However, never break user-visible strings such as
99 ----------------------------
107 .. code-block:: c
113 This applies to all non-function statement blocks (if, switch, for,
116 .. code-block:: c
132 .. code-block:: c
140 is ... well ... inconsistent, but all right-thinking people know that
146 ie a ``while`` in a do-statement or an ``else`` in an if-statement, like
149 .. code-block:: c
152 body of do-loop
157 .. code-block:: c
169 Also, note that this brace-placement also minimizes the number of empty
171 supply of new-lines on your screen is not a renewable resource (think
172 25-line terminal screens here), you have more empty lines to put
177 .. code-block:: c
184 .. code-block:: none
194 .. code-block:: c
205 .. code-block:: c
216 function-versus-keyword usage. Use a space after (most) keywords. The
228 .. code-block:: c
236 .. code-block:: c
245 .. code-block:: c
255 = + - < > * / % | & ^ <= >= == != ? :
259 & * + - ~ ! sizeof typeof alignof __attribute__ defined
263 ++ --
267 ++ --
269 and no space around the ``.`` and ``->`` structure member operators.
285 ---------
287 C is a Spartan language, and so should your naming be. Unlike Modula-2
293 HOWEVER, while mixed-case names are frowned upon, descriptive names for
298 have descriptive names, as do global functions. If you have a function
302 Encoding the type of a function into the name (so-called Hungarian
303 notation) is brain damaged - the compiler knows the types anyway and can
309 Calling it ``loop_counter`` is non-productive, if there is no chance of it
310 being mis-understood. Similarly, ``tmp`` can be just about any type of
314 problem, which is called the function-growth-hormone-imbalance syndrome.
319 -----------
324 .. code-block:: c
332 .. code-block:: c
361 Again - there needs to be a **reason** for this. If something is
371 type-checking.
380 Therefore, the Linux-specific ``u8/u16/u32/u64`` types and their
382 permitted -- although they are not mandatory in new code of your
403 ------------
412 case-statement, where you have to do lots of small things for a lot of
416 less-than-gifted first-year high-school student might not even
419 descriptive names (you can ask the compiler to in-line them if you think
420 it's performance-critical, and it will probably do a better job of it
424 shouldn't exceed 5-10, or you're doing something wrong. Re-think the
434 .. code-block:: c
451 -----------------------------------
462 Avoid using GW-BASIC names like ``err1:`` and ``err2:``, as you would have to
468 - unconditional statements are easier to understand and follow
469 - nesting is reduced
470 - errors by not updating individual exit points when making
472 - saves the compiler work to optimize redundant code away ;)
474 .. code-block:: c
483 return -ENOMEM;
500 .. code-block:: c
503 kfree(foo->bar);
511 .. code-block:: c
514 kfree(foo->bar);
523 -------------
525 Comments are good, but there is also a danger of over-commenting. NEVER
539 When commenting the kernel API functions, please use the kernel-doc format.
540 See the files at :ref:`Documentation/doc-guide/ <doc_guide>` and
541 ``scripts/kernel-doc`` for details.
543 The preferred style for long (multi-line) comments is:
545 .. code-block:: c
548 * This is the preferred style for multi-line
553 * with beginning and ending almost-blank lines.
556 For files in net/ and drivers/net/ the preferred style for long (multi-line)
559 .. code-block:: c
565 * but there is no initial almost-blank line.
575 ---------------------------
577 That's OK, we all do. You've probably been told by your long-time Unix
581 typing - an infinite number of monkeys typing into GNU emacs would never
587 .. code-block:: none
589 (defun c-lineup-arglist-tabs-only (ignored)
591 (let* ((anchor (c-langelem-pos c-syntactic-element))
592 (column (c-langelem-2nd-pos c-syntactic-element))
593 (offset (- (1+ column) anchor))
594 (steps (floor offset c-basic-offset)))
596 c-basic-offset)))
598 (dir-locals-set-class-variables
599 'linux-kernel
600 '((c-mode . (
601 (c-basic-offset . 8)
602 (c-label-minimum-indentation . 0)
603 (c-offsets-alist . (
604 (arglist-close . c-lineup-arglist-tabs-only)
605 (arglist-cont-nonempty .
606 (c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
607 (arglist-intro . +)
608 (brace-list-intro . +)
609 (c . c-lineup-C-comments)
610 (case-label . 0)
611 (comment-intro . c-lineup-comment)
612 (cpp-define-intro . +)
613 (cpp-macro . -1000)
614 (cpp-macro-cont . +)
615 (defun-block-intro . +)
616 (else-clause . 0)
617 (func-decl-cont . +)
619 (inher-cont . c-lineup-multi-inher)
620 (knr-argdecl-intro . 0)
621 (label . -1000)
623 (statement-block-intro . +)
624 (statement-case-intro . +)
625 (statement-cont . +)
628 (indent-tabs-mode . t)
629 (show-trailing-whitespace . t)
632 (dir-locals-set-directory-class
633 (expand-file-name "~/src/linux-trees")
634 'linux-kernel)
637 files below ``~/src/linux-trees``.
642 Now, again, GNU indent has the same brain-dead settings that GNU emacs
647 options ``-kr -i8`` (stands for ``K&R, 8 character indents``), or use
651 re-formatting you may want to take a look at the man page. But
654 Note that you can also use the ``clang-format`` tool to help you with
655 these rules, to quickly re-format parts of your code automatically,
659 See the file :ref:`Documentation/process/clang-format.rst <clangformat>`
664 -------------------------------
677 logging of avc messages output). Does not do system-call
689 Documentation/kbuild/kconfig-language.rst.
693 -------------------
695 Data structures that have visibility outside the single-threaded
702 users to have access to the data structure in parallel - and not having
716 Examples of this kind of ``multi-level-reference-counting`` can be found in
725 -------------------------
729 .. code-block:: c
740 Macros with multiple statements should be enclosed in a do - while block:
742 .. code-block:: c
754 .. code-block:: c
759 return -EBUGGERED; \
767 .. code-block:: c
774 3) macros with arguments that are used as l-values: FOO(x) = y; will
781 .. code-block:: c
789 .. code-block:: c
798 ret is a common name for a local variable - __foo_ret is less likely
806 ----------------------------
826 debug message printing is handled differently than printing other non-debug
833 Many subsystems have Kconfig debug options to turn on -DDEBUG in the
836 already inside a debug-related #ifdef section, printk(KERN_DEBUG ...) can be
841 ---------------------
846 about them. :ref:`Documentation/core-api/memory-allocation.rst
851 .. code-block:: c
865 .. code-block:: c
871 .. code-block:: c
883 ----------------------
911 ------------------------------------
915 failed. Such a value can be represented as an error-code integer
916 (-Exxx = failure, 0 = success) or a ``succeeded`` boolean (0 = failure,
917 non-zero = success).
920 difficult-to-find bugs. If the C language included a strong distinction
926 the function should return an error-code integer. If the name
930 for success or -EBUSY for failure. In the same way, ``PCI device present`` is
940 this rule. Generally they indicate failure by returning some out-of-range
946 --------------
970 readable alternative if the call-sites have naked true/false constants.
975 18) Don't re-invent the kernel macros
976 -------------------------------------
983 .. code-block:: c
989 .. code-block:: c
991 #define FIELD_SIZEOF(t, f) (sizeof(((t*)0)->f))
999 ------------------------------------
1005 .. code-block:: c
1007 -*- mode: c -*-
1011 .. code-block:: c
1015 compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
1021 .. code-block:: c
1033 -------------------
1035 In architecture-specific code, you may need to use inline assembly to interface
1044 Large, non-trivial assembly functions should go in .S files, with corresponding
1057 .. code-block:: c
1065 ---------------------------
1070 files, providing no-op stub versions in the #else case, and then call those
1089 .. code-block:: c
1095 The compiler will constant-fold the conditional away, and include or exclude
1102 At the end of any non-trivial #if or #ifdef block (more than a few lines),
1106 .. code-block:: c
1114 ----------------------
1119 ISBN 0-13-110362-8 (paperback), 0-13-110370-9 (hardback).
1123 Addison-Wesley, Inc., 1999.
1124 ISBN 0-201-61586-X.
1126 GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
1130 language C, URL: http://www.open-std.org/JTC1/SC22/WG14/
1132 Kernel :ref:`process/coding-style.rst <codingstyle>`, by greg@kroah.com at OLS 2002: