Linux coding Style

1, https://wenku.baidu.com/view/29009a84bceb19e8b8f6badc.html

2, http://blog.csdn.net/stuartguo/article/details/52065642

Chinese translated version of documentation/codingstyle if you has any comment or update to the content, please post To LKML directly. However, if you have problem communicating in 中文版 you can also ask Thechinese maintainer for help.  contact the Chinese maintainer, if thistranslation is outdated or there are problem with Translation. chinese MA Intainer:zhang Le <[email protected]>---------------------------------------------------------------- -----Documentation/codingstyle Chinese Translation   If you would like to comment or update the contents of this article, please send a letter directly to LKML. If you have difficulty communicating in English, you can also ask the Chinese version of the maintainer for help. If this translation is not updated or if there is a problem with the translation, please contact the Chinese version maintainer.   Chinese maintainer: Le Zhang Zhang le <[email protected]> Chinese translator: Le Zhang Zhang le <[email protected]> Chinese translator: Cong Wang Cong <[email protected]>               wheelz <[email  protected]>                You Xudong Xudong Guan <[email protected]>               li Zefan <[email protected]>               wang Chen <[email& Nbsp;protected]> The following is the body--------------------------------------------------------------------- linux kernel code style   This is a short document that describes the preferred code style for the Linux kernel. The code style is personal, and I don't want to impose my views on anyone, but here's what I have to do to maintain the style of the code, and I hope that most of the other code will follow this style as well. Please do not consider the style described in this article until you write your code.   First, I recommend that you print a copy of the GNU Code specification, and then do not read it. Burn it, this is a symbolic gesture of great significance.   Anyway, now we start:    the first chapter: Indent   tab is 8 characters, so the indentation is also 8 characters. Some heretical movements attempt to! Characters the indentation into 4 (or even 2) characters, which is almost equivalent to trying to define the value of pi as 3.   Reason: The whole point of indentation is to clearly define where a control block starts and ends. Especially if you look at your screen for 20 hours straight, you'll find that a larger indent will make it easier to distinguish between indents.   Now, some people will complain that a 8-character indent will make the code move too far to the right, and it's hard to read code on a 80-character terminal screen. The answer to this question is that if you need to indent more than 3 levels, no matter how your code is already in question, you should fix your program.   In short, 8-character indentation can make your code easier to read, and one benefit is that you can warn you when your function is nested too deep. Heed the warning.   The preferred way to eliminate multilevel indentation in a switch statement is to have "switch" aligned to the same column as the "case" label that belongs to it, rather than "indent the case" label two times. Example:  switch (suffix) {case ' G ': Case ' G ': Mem <<= 30;break;case ' m ': Case ' m ': Mem <<= 20;break;case ' K ': case ' K ': Mem <<= 10;/* FALL through */default:break;}    don't put multiple statements in one line unless you have something to hide:  if (condition) do_this;  do_something_everytime;  Also do not put multiple assignment statements in a row. The kernel code style is super simple. is to avoid expressions that can cause others to misread.   In addition to annotations, documents, and Kconfig, do not use spaces to indent, the previous example is an exception, is intentional.   Choose a good editor, do not leave spaces at the end of the line.    Chapter II: Breaking Long Lines and strings   code style is about using the tools that you normally use to maintain the readability and maintainability of your code.   The limit for the length of each line is 80 columns, and we strongly recommend that you follow this practice.   statements that are longer than 80 columns are broken into meaningful fragments. Each fragment is significantly shorter than the original statement, and the position is clearly positioned on the right. The same rules apply to function headers with very long parameter lists. Long strings also break into shorter strings. The only exception is when more than 80 columns can significantly improve readability and do not hide information.  void Fun (int A, int b, int c) {if (condition) PRINTK (kern_warning "WARNING"-a long PRINTK with "" 3 parameters A :%u B:%u "" C:%u \ n ", A, B, c); elsenext_statement;}   Chapter Three: placement of braces and spaces  c Another common problem in language style is the placement of curly braces. Unlike indentation size, there is not much technical reason to choose or discard a placement strategy, but the preferred way, as Kernighan and Ritchie show us, is to put the opening brace at the end of the line and put the closing brace at the beginning of the line, so:  if (x is True) { We do y}  this applies to all non-function statement blocks (if, switch, for, while, do). For example:  switch (action) {case Kobj_add:return ' ADD ', Case Kobj_remove:return ' REMOVE ', Case Kobj_change:return ' change ' ;d Efault:return NULL;}   However, with one exception, it is the function: The starting brace of the function is placed at the beginning of the next line, so:  int function (int x) {Body of function}  the world's heretics may complain that this inconsistency is ... Uh...... Inconsistent, but all sane people know that (a) K&r is _ correct _, and (b) K&r is correct. In addition, functions are special in any case (in C, functions cannot be nested).   Note that the closing brace occupies a single line, unless it follows the remainder of the same statement, the "while" in the Do statement, or "else" in the IF statement, like this:  do {body of Do-loop} while ( Condition);  and  if (x = = y) {..} else if (x > Y) {...} else {...}   Reason: K&r.   Also note that the placement of curly braces can minimize the number of empty (or almost empty) rows without losing readability. Therefore, because the new line on your screen is non-renewable (think of the 25-line terminal screen), you will have more empty lines to place the comments.   When there is only one single statement, do not add unnecessary curly braces.  if (condition) action ();  this does not apply to individual statements that are itself a branch of a conditional statement. In this case, you need to use curly braces in all two branches.  if (condition) {do_this ();d o_that ();} else {otherwise ();}  3.1: Space  linux The space used by the kernel (mostly) depends on whether it is used for functions or keywords. Add a space after the (most) keyword. Notable exceptions are sizeof, typeof, Alignof, and __attribute__, which appear to some extent more like functions (they are often used with parentheses in Linux, although such parentheses are not required in C, like " "sizeof info" after the struct FileInfo info declaration).   So put a space after these keywords: if, switch, case, for, does, while but do not empty the grid after the keywords sizeof, typeof, Alignof, or __attribute__. For example, s = sizeof (struct file);  do not put spaces on either side of the expression in parentheses. This is a counter example:  s = sizeof (struct file);  when you declare a pointer type or a function that returns a pointer type, the preferred way to use "*" is to close the variable name or function name, not near the type name. Example:  char *linux_banner;unsigned Long Long memparse (char *ptr, char **retptr); char *match_strdup (substring_t *s); nbsp; Use a space on both sides of the most two and ternary operators, such as all of these operators:  =  +  - <  >  *  / %  |  &  ^  <=  >=  ==  !=  ?  :  but do not add a space after the unary operator:&  *  +  - ~  !  sizeof  typeof  alignof  __attribute__  defined  suffix Add and subtract unary operators without spaces before: + +  --  Prefix self-plus and decrement unary operators without spaces: + +  --  "." And the struct member operators are not preceded by spaces.   Do not leave blank at the end of the line. Some editors that can be automatically indented add an appropriate amount of whitespace to the beginning of a new line, and then you can enter the code directly on that line. But if you don't enter the code at the end of the line, some editors won't remove the whitespace you've added, as if you deliberately left a blank line. The line that contains the trailing blanks is created.   When Git finds that the patch contains a line-end blank, it warns you, and can remove the line-end whitespace at your request, but if you are playing a series of patches, doing so will cause subsequent patches to fail because you changed the context of the patch.    Fourth: Naming  c is a simple language, your name should be the same. Unlike Modula-2 and Pascal programmers, C programmers do not use similar ThisvariableisatemporarYcounter such a gorgeous name. C programmers would call that variable "TMP", which would make it easier to write, and at least not make it difficult to understand.   However, while mixed-case names are deprecated, global variables require a descriptive name. Calling a global function "foo" is a difficult mistake to forgive.   Global variables (which are used only when you really need them) need to have a descriptive name, like a global function. If you have a function that can count the number of active users, you should call it "count_active_users ()" or a similar name, and you should not call it "Cntuser ()".   Include the function type in the function name (the so-called Hungarian nomenclature) is the brain problem-the compiler knows those types and can check those types, which can only confuse the programmer. No wonder Microsoft is always creating problematic programs.   local variable names should be short and can convey relevant meanings. If you have some random integer-type loop counter, it should be called "I". It is not beneficial to call it "loop_counter" if it is not misunderstood. Similarly, "TMP" can be used to address any type of temporary variable.   If you're afraid of confusing your local variable name, you're experiencing another problem called the function Growth Hormone imbalance syndrome. See chapter Sixth (function).    Fifth:typedef  do not use something like "vps_t".   using typedef on structs and pointers is an error. When you see in the code:  vps_t a;  What does that mean?   Conversely, if so  struct virtual_container *a;  you know what "a" is.   Many people think that typedef "can improve readability". This is not actually the case. They are useful only in the following cases:   (a) completely opaque objects (in which case it is important to actively use a typedef to hide what this object actually is).        For example: opaque objects such as "pte_t", you can access them only with the appropriate access functions.        NOTE! Opacity and the "access function" itself are not good. The reason we use pte_t and other types is that it really is       There is no shared accessible information at all.    (b) A clear integer type, so that this layer of abstraction can help eliminate the "int"or" long "confusion.      &NBSP;U8/U16/U32 are completely non-problematic typedef, but they are more in line with category (d) rather than here.        Pay attention again! To do so, there must be a reason. If a variable is "unsigned long", then it is not necessary  typedef unsigned long myflags_t;       But if there is a definite reason, For example, it may be a "unsigned int" in some cases and in       Other cases may be "unsigned long", then do not hesitate, be sure to use typedef.    (c) When you use sparse to literally create a new type to do type checking.    (d) the same type as the standard C99 type, in the case of certain exceptions.        Although it takes a lot of time to adapt your eyes and brains to new standard types like "uint32_t", some       people still refuse to use them.        Therefore, Linux-specific "u8/u16/u32/u64" types that are equivalent to standard types and their signed types are allowed by      -although in your own new code, They are not mandatory requirements to be used.        When editing existing code that already uses a set of types, you should follow the choices already made in those codes.    (e) types that can be safely used in user space.        In some user-space-visible structures, we cannot ask for C99 types and cannot use the "u32"       types mentioned above. Therefore, we use __U32 and similar types in all structures that are shared with user space.   There may be other situations, but the basic rule is never to use a typedef unless you can explicitly apply one of these rules.   In general, if a pointer or an element in a struct can be reasonably accessed directly, then they should not be a typedef.    Sixth: Functions   functionsshould be short and beautiful, and only do one thing. The function should be displayed on one screen or two screens (we all know that the Iso/ansi screen size is 80x24), just do one thing and do it well.   The maximum length of a function is inversely proportional to the complexity of the function and the indentation progression. So, if you have a theoretically simple function of a very long (but simple) case statement, and you need to do a lot of small things in each case, such a function, though long, is fine.   However, if you have a complex function, and you suspect a high school freshman with a talent that is not very high may even be confused about the purpose of this function, you should strictly abide by the length limit mentioned earlier. Use auxiliary functions and give them descriptive names (if you think their performance is important, you can let the compiler inline them, which tends to be better than writing a complex function.) Another metric for the   function is the number of local variables. This number should not exceed 5-10, otherwise your function will have a problem. Reconsider your function and split it into smaller functions. The human brain can generally easily track 7 different things at the same time, and if you increase it, you will be confused. Even if you are smart, you may not remember what you did 2 weeks ago.   In the source file, use a blank line to separate the different functions. If the function needs to be exported, its export* macro should cling to its closing curly brace. For example:  int system_is_up (void) {return system_state = = system_running;} Export_symbol (SYSTEM_IS_UP);  in a function prototype, contains the names of functions and their data types. Although there is no such requirement in the C language, it is advocated in Linux, as it is a simple way to provide more valuable information to the reader.    Seventh: Centralized function exit path   Although some people claim to be obsolete, the equivalent of a goto statement is often used by the compiler, in the form of an unconditional jump instruction.   The benefits of Goto appear when a function exits from multiple locations and needs to do some general cleanup.   reasons:  -unconditional statements are easy to understand and track-less nesting-can avoid errors caused by forgetting to update a separate exit point due to modifications-reducing the compiler's work without removing redundant code;)  int Fun (int a) {int result = 0;char *buffer = Kmalloc (SIZE); &nbspif (buffer = = NULL) return-enomem; if (condition1) {while (LOOP1) {...} result = 1;goto out;} ... out:kfree (buffer); return result;}   Eighth: Comments   comments are good, but there is a risk of over-commenting. Never explain how your code works in comments: It's a good idea to let someone read your code to understand that it's a waste of time to interpret poorly written code.   In general, you want your comments to tell others what your code did, not how to do it. Please do not put the comment inside a function body: If the function is complex and you need a separate comment part, you probably need to go back to the sixth chapter to see it. You can make small notes to indicate or warn of some very clever (or cake) practices, but don't add too much. What you should do is put the comment on the head of the function, tell people what it does, and add the reason for it to do these things.   When commenting on kernel API functions, use the Kernel-doc format. See Documentation/kernel-doc-nano-howto.txt and Scripts/kernel-doc for more information.  linux's annotation style is C89 "/* ... * *" style. Do not use the C99 style "//..." comment. The preferred annotation style for   long (multi-line) is:  /* * the preferred style for multi-line * comments in the Linux kernel source code. * consistently. * * Description:  a column of asterisks on the left side, * W ith beginning and ending Almost-blank lines. */  annotation data is also important, whether it is a base type or a derived type. To facilitate this, each row should declare only one data (do not use commas to declare multiple data at a time). This gives you the space to write a small note of each data to explain their usefulness.    Nineth: You've messed things up   It's nothing, we all do. Maybe it's your use.For a long time, a friend of Unix has told you that GNU Emacs will automatically help you format C source code, and you notice that it does, but the default value it uses is a far cry from what we want (in fact, even worse than a random hit – countless monkeys in GNU The typing in Emacs will never create a good program (see Infinite Monkey theorem)   So you either give up GNU Emacs or change it to use more reasonable settings. To use the latter scenario, you can paste the following paragraph into your. emacs file.   (Defun linux-c-mode ()   "C mode with adjusted defaults for use with the Linux kernel."   (interactive)   (C-mode)   (c-set-style "K&r")   (setq tab-width 8)   (setq Indent-tabs-mode T)   (SETQ C-basic-offset 8)   This defines the M-x linux-c-mode command. When you hack a module, if you put the string-*-linux-c-*-in a position on the first two lines, the pattern will be automatically called. You may also need to add   (setq auto-mode-alist ("cons") if you wish to automatically open Linux-c-mode when you modify the files in/usr/src/linux. *\\. [ch]$]. Linux-c-mode, auto-mode-alist)   into your. emacs file.   But even if you try to get Emacs to properly format the code, it doesn't mean you've lost everything: you can also use "indent".   However, the GNU indent has the same problematic settings as GNU Emacs, so you need to give it some command options. However, this is not too bad, because even the authors of the GNU indent agree with K&r's authority (GNU people are not bad, they are only seriously misled on this issue), so you just give indent the option "-kr-i8" (for "K&r", 8 character indent "), or use" scripts/lindent ", so you canTrendy way to indent source code.   "Indent" has a lot of options, especially when reformatting a comment, you might want to look at its manual page. But remember: "Indent" can't fix bad programming habits.    Tenth: Kconfig profile   for all kconfig* configuration files that are spread over the source tree, they are indented differently than C code. A tab is indented next to the line below the "config" definition, and the help message indents 2 more spaces. For example:  config auditbool "Auditing support" depends on nethelp  enable Auditing infrastructure so can be used With Another  kernel subsystem, such as SELinux (which requires the for  logging of AVC messages out Put).  does not do system-call  auditing without config_auditsyscall.  is still considered to be unstable and should be defined as dependent on " Experimental ":  config slubdepends on experimental &&! Arch_uses_slab_page_structbool "Slub (unqueued Allocator)" ...  and those dangerous features (such as write support for some file systems) should be declared prominently in their cue strings:  config Adfs_fs_rwbool "ADFS write Support (dangerous)" depends on adfs_fs...  to view the complete documentation for the configuration file, see documentation/ Kbuild/kconfig-language.txt.    11th: Data Structures   If a data structure is visible outside of the single-threaded execution environment where it is created and destroyed, then it must have a reference counter. There is no garbage collection in the kernel (and garbage collection outside the kernel is slow and inefficient), which means you absolutely need to record your use of this data structure. &nbThe reference count means that you can avoid locking and allow multiple users to access the data structure in parallel-without worrying that the data structure disappears just because it is temporarily unused, and that the user may have just slept or done something else.   Note that locking does not replace reference counting. Locking is to keep the data structure consistent, whereas reference counting is a memory management technique. Usually both need to be, don't confuse the two.   Many data structures actually have a 2-level reference count, and they usually have different "classes" of users. The sub-class counter counts the number of subclass users, and the global counter is reduced by one whenever the subclass counter is reduced to 0 o'clock.   This "multilevel reference count" example can be found in memory management ("struct mm_struct": Mm_users and Mm_count) and the file system ("struct Super_block": S_count and S_active).   Remember: If another thread of execution can find your data structure, but this structure doesn't reference the counter, it's almost certainly a bug.    12th: macros, enumerations, and rtl  the names of the macros used to define constants and the tags in the enumeration need to be capitalized.   #define CONSTANT 0x12345  It is best to use enumerations when defining several related constants.   The name of the macro is capitalized, but the name of the macro like the function can be in lowercase letters.   Generally, if you can write inline functions, do not write macros like functions.   Macros containing multiple statements should be included in a do-while code block:  #define MACROFUN (A, B, c)    \do {\if (a = = 5) \do_this (b, c); \} while (0)   things to avoid when using macros: &NBSP;1) The macro:  that affects the control process #define FOO (x) \do {\if (blah (x) < 0) \return-ebuggered; \} while (0) &N BSP; very bad. It looks like a function, but it can cause "call" its function to exit; Do not disrupt the parser in the reader's brain. &NBSP;2) A macro that relies on a local variable of a fixed name:  #define FOO (val) bar (Index, Val)   may seem like a good thing, but it's very easy to confuse people who read the code, It is also easy to cause errors in seemingly unrelated changes. &NBSP;3) A macro with parameters as an lvalue: foo (x) = y; if someone turns foo into an inline function, this usage will go wrong.  4) forgot precedence: a macro that uses an expression to define a constant must place the expression inside a pair of parentheses. Macros with parameters should also be aware of such problems.   #define CONSTANT 0x4000#define constexp (CONSTANT | 3) The &NBSP;CPP manual explains the macro in detail. The GCC Internals Manual also details the RTL (Registertransfer language), which is often used in assembly language in the kernel.    13th: Print kernel messages   Kernel developers should be well-educated. Be sure to note the spelling of the kernel information to give a good impression. Instead of using non-canonical words such as "dont", use "do not" or "Don t". Ensure that the information is simple, clear and unambiguous.   Kernel information does not have to end with a full period, that is, point.   Printing numbers in parentheses (%d) has no value and should be avoided.  <linux/device.h> has some driver model diagnostics macros that you should use to make sure that the information corresponds to the correct device and driver, and that the correct message level is flagged. These macros are: Dev_err (), Dev_warn (), Dev_info (), and so on. For information,<linux/kernel.h> that are not associated with a particular device, pr_debug () and pr_info () are defined.   Writing good debugging information can be a big challenge, and when you write it out, it will be a great help when you remove the error remotely. When the debug symbol is not defined, the information should not be compiled into the kernel (i.e., by default, they should not be included). If you use dev_dbg () or Pr_debug (), you can automatically achieve this effect. Many subsystems have the Kconfig option to enable-ddebug. A related convention is to use Verbose_debug to add dev_vdbg () messages to messages that have already been enabled by Debug.    14th: Allocating memory   The kernel provides the following general-purpose memory allocation functions: Kmalloc (), Kzalloc (), Kcalloc (), and Vmalloc (). Refer to the API documentation for more information about them. The preferred form of   transfer structure size is this:  p= Kmalloc (sizeof (*P), ...);   Another way of passing on, sizeof's operand is the name of the struct, which reduces readability and may introduce bugs. It is possible that when the pointer variable type is changed, the corresponding result of sizeof passed to the memory allocation function is unchanged.   Casting a void pointer returns a value that is superfluous. The C language itself guarantees that the conversion from the void pointer to any other pointer type is not a problem.    15th: Inline ills   There is a common misconception that inline functions are an option that GCC provides that allows the code to run faster. Although it is sometimes appropriate to use inline functions (for example, as an alternative to macros, see Chapter 12th), in many cases this is not the case. The over-use of the inline keyword makes the kernel larger, making the whole system slower. Because the larger kernel consumes more instruction caches (the first-level cache is usually separate from the instruction cache and the data cache) and causes the Pagecache to reduce the available memory. Imagine that a pagecache miss would result in one disk addressing at a time that would take 5 milliseconds. The CPU can execute many and many instructions in 5 milliseconds.   A basic principle is that if a function has more than 3 rows, do not turn it into an inline function. An exception to this principle is that if you know that a parameter is a compile-time constant, and because you are sure that the compiler can optimize most of your function's code when compiling it, you can still add the inline keyword to it. The Kmalloc () inline function is a good example.   People often advocate for static and only once functions with inline, so there is no loss, because there is no good tradeoff. This is technically true, but in fact this situation can be automatically linked even without the inline gcc. and other users may ask for the removal of the inline, the resulting controversy will offset the potential value of the inline itself, not worth the candle.    16th: function return values and naming   functions can return many different types of values, the most common being a value indicating the success or failure of a function execution. Such a value can be represented as an error code integer (-exxx= failed, 0 = successful) or a "Success" Boolean value (0= failed, not 0 = successful).   Mixed use of these two expressions is a source of bugs that are difficult to spot. If the C language itself strictly distinguishes between shaping and Boolean variables, then the compiler will be able to help us find these errors ... But the C language does not differentiate. To avoid this bug, follow the conventions below:  if the name of the function is an action or a mandatory command, thenThis function should return the error code integer. If it is a judgment, then the function should return a "success" Boolean value.   For example, "Add Work" is a command, so the Add_work () function returns 0 on success and returns-EBUSY on failure. Similarly, because "PCI device present" is a judgment, the pci_dev_present () function should return 1 if it finds a matching device successfully, and should return 0 if it is not found.   All functions that derive from export are subject to this Convention, as should all public functions. This is not required for private (static) functions, but we also recommend doing so. The   return value is a function of the flag that actually evaluates the result rather than the success of the calculation is not limited by this Convention. In general, they indicate an error by returning some results outside the range of normal values. A typical example is a function that returns pointers, which use NULL or ERR_PTR mechanisms to report errors.    17th: Don't reinvent the kernel macro   header file Include/linux/kernel.h contains some macros that you should use instead of writing some of their variants yourself. For example, if you need to calculate the length of an array, use this macro    #define ARRAY_SIZE (x) (sizeof (x)/sizeof ((x) [0]))   Similar, if you want to calculate the size of a struct member, use    #define FIELD_SIZEOF (T, f) (SIZEOF (((t*) 0)->f)   There are also min () and Max () macros that can do strict type checking if you need to be able to use them. You can see for yourself what else you can use in that file, and if you have a definition, you shouldn't redefine it yourself in your code.    18th: Editor Mode Lines and other things to wordy   some editors can interpret configuration information embedded in the source file by some special tags. For example, Emacs can explain the lines that are labeled as:  -*-mode:c-*-  or something like this:  /*local variables:compile-command: "Gcc-dmagic_debug_ Flag FOO.C "End:*/ vim can explain such a tag:  /* vim:set sw=8 Noet */  do not include any of these in the source codeThe content. Everyone has his own editor configuration, and your source files should not be overwritten by someone else's configuration. This includes markup about indentation and pattern configuration. People can use their own custom patterns, or use other ingenious methods that can produce the correct indentation.

Linux encoding Style (RPM)