aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorRandy Dunlap <rdunlap@xenotime.net>2006-06-23 05:05:58 -0400
committerLinus Torvalds <torvalds@g5.osdl.org>2006-06-23 10:43:08 -0400
commit226a6b84aaaf1fac7a5d41cf4e7387fd9ba895d5 (patch)
treef1d72ef1145ddbd108c2701e1154fb81e078adb3 /Documentation
parent3439dd86e34580384d3b58cf8d54a9283cd7a342 (diff)
[PATCH] CodingStyle: add typedefs chapter
Add a chapter on typedefs, copied from an email from Linus to lkml on Feb. 3, 2006. (Subject: Re: [RFC][PATCH 1/5] Virtualization/containers: startup) Signed-off-by: Randy Dunlap <rdunlap@xenotime.net> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/CodingStyle100
1 files changed, 88 insertions, 12 deletions
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
index ce5d2c038cf..6d2412ec91e 100644
--- a/Documentation/CodingStyle
+++ b/Documentation/CodingStyle
@@ -155,7 +155,83 @@ problem, which is called the function-growth-hormone-imbalance syndrome.
155See next chapter. 155See next chapter.
156 156
157 157
158 Chapter 5: Functions 158 Chapter 5: Typedefs
159
160Please don't use things like "vps_t".
161
162It's a _mistake_ to use typedef for structures and pointers. When you see a
163
164 vps_t a;
165
166in the source, what does it mean?
167
168In contrast, if it says
169
170 struct virtual_container *a;
171
172you can actually tell what "a" is.
173
174Lots of people think that typedefs "help readability". Not so. They are
175useful only for:
176
177 (a) totally opaque objects (where the typedef is actively used to _hide_
178 what the object is).
179
180 Example: "pte_t" etc. opaque objects that you can only access using
181 the proper accessor functions.
182
183 NOTE! Opaqueness and "accessor functions" are not good in themselves.
184 The reason we have them for things like pte_t etc. is that there
185 really is absolutely _zero_ portably accessible information there.
186
187 (b) Clear integer types, where the abstraction _helps_ avoid confusion
188 whether it is "int" or "long".
189
190 u8/u16/u32 are perfectly fine typedefs, although they fit into
191 category (d) better than here.
192
193 NOTE! Again - there needs to be a _reason_ for this. If something is
194 "unsigned long", then there's no reason to do
195
196 typedef unsigned long myflags_t;
197
198 but if there is a clear reason for why it under certain circumstances
199 might be an "unsigned int" and under other configurations might be
200 "unsigned long", then by all means go ahead and use a typedef.
201
202 (c) when you use sparse to literally create a _new_ type for
203 type-checking.
204
205 (d) New types which are identical to standard C99 types, in certain
206 exceptional circumstances.
207
208 Although it would only take a short amount of time for the eyes and
209 brain to become accustomed to the standard types like 'uint32_t',
210 some people object to their use anyway.
211
212 Therefore, the Linux-specific 'u8/u16/u32/u64' types and their
213 signed equivalents which are identical to standard types are
214 permitted -- although they are not mandatory in new code of your
215 own.
216
217 When editing existing code which already uses one or the other set
218 of types, you should conform to the existing choices in that code.
219
220 (e) Types safe for use in userspace.
221
222 In certain structures which are visible to userspace, we cannot
223 require C99 types and cannot use the 'u32' form above. Thus, we
224 use __u32 and similar types in all structures which are shared
225 with userspace.
226
227Maybe there are other cases too, but the rule should basically be to NEVER
228EVER use a typedef unless you can clearly match one of those rules.
229
230In general, a pointer, or a struct that has elements that can reasonably
231be directly accessed should _never_ be a typedef.
232
233
234 Chapter 6: Functions
159 235
160Functions should be short and sweet, and do just one thing. They should 236Functions should be short and sweet, and do just one thing. They should
161fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, 237fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
@@ -183,7 +259,7 @@ and it gets confused. You know you're brilliant, but maybe you'd like
183to understand what you did 2 weeks from now. 259to understand what you did 2 weeks from now.
184 260
185 261
186 Chapter 6: Centralized exiting of functions 262 Chapter 7: Centralized exiting of functions
187 263
188Albeit deprecated by some people, the equivalent of the goto statement is 264Albeit deprecated by some people, the equivalent of the goto statement is
189used frequently by compilers in form of the unconditional jump instruction. 265used frequently by compilers in form of the unconditional jump instruction.
@@ -220,7 +296,7 @@ out:
220 return result; 296 return result;
221} 297}
222 298
223 Chapter 7: Commenting 299 Chapter 8: Commenting
224 300
225Comments are good, but there is also a danger of over-commenting. NEVER 301Comments are good, but there is also a danger of over-commenting. NEVER
226try to explain HOW your code works in a comment: it's much better to 302try to explain HOW your code works in a comment: it's much better to
@@ -240,7 +316,7 @@ When commenting the kernel API functions, please use the kerneldoc format.
240See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc 316See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
241for details. 317for details.
242 318
243 Chapter 8: You've made a mess of it 319 Chapter 9: You've made a mess of it
244 320
245That's OK, we all do. You've probably been told by your long-time Unix 321That's OK, we all do. You've probably been told by your long-time Unix
246user helper that "GNU emacs" automatically formats the C sources for 322user helper that "GNU emacs" automatically formats the C sources for
@@ -288,7 +364,7 @@ re-formatting you may want to take a look at the man page. But
288remember: "indent" is not a fix for bad programming. 364remember: "indent" is not a fix for bad programming.
289 365
290 366
291 Chapter 9: Configuration-files 367 Chapter 10: Configuration-files
292 368
293For configuration options (arch/xxx/Kconfig, and all the Kconfig files), 369For configuration options (arch/xxx/Kconfig, and all the Kconfig files),
294somewhat different indentation is used. 370somewhat different indentation is used.
@@ -313,7 +389,7 @@ support for file-systems, for instance) should be denoted (DANGEROUS), other
313experimental options should be denoted (EXPERIMENTAL). 389experimental options should be denoted (EXPERIMENTAL).
314 390
315 391
316 Chapter 10: Data structures 392 Chapter 11: Data structures
317 393
318Data structures that have visibility outside the single-threaded 394Data structures that have visibility outside the single-threaded
319environment they are created and destroyed in should always have 395environment they are created and destroyed in should always have
@@ -344,7 +420,7 @@ Remember: if another thread can find your data structure, and you don't
344have a reference count on it, you almost certainly have a bug. 420have a reference count on it, you almost certainly have a bug.
345 421
346 422
347 Chapter 11: Macros, Enums and RTL 423 Chapter 12: Macros, Enums and RTL
348 424
349Names of macros defining constants and labels in enums are capitalized. 425Names of macros defining constants and labels in enums are capitalized.
350 426
@@ -399,7 +475,7 @@ The cpp manual deals with macros exhaustively. The gcc internals manual also
399covers RTL which is used frequently with assembly language in the kernel. 475covers RTL which is used frequently with assembly language in the kernel.
400 476
401 477
402 Chapter 12: Printing kernel messages 478 Chapter 13: Printing kernel messages
403 479
404Kernel developers like to be seen as literate. Do mind the spelling 480Kernel developers like to be seen as literate. Do mind the spelling
405of kernel messages to make a good impression. Do not use crippled 481of kernel messages to make a good impression. Do not use crippled
@@ -410,7 +486,7 @@ Kernel messages do not have to be terminated with a period.
410Printing numbers in parentheses (%d) adds no value and should be avoided. 486Printing numbers in parentheses (%d) adds no value and should be avoided.
411 487
412 488
413 Chapter 13: Allocating memory 489 Chapter 14: Allocating memory
414 490
415The kernel provides the following general purpose memory allocators: 491The kernel provides the following general purpose memory allocators:
416kmalloc(), kzalloc(), kcalloc(), and vmalloc(). Please refer to the API 492kmalloc(), kzalloc(), kcalloc(), and vmalloc(). Please refer to the API
@@ -429,7 +505,7 @@ from void pointer to any other pointer type is guaranteed by the C programming
429language. 505language.
430 506
431 507
432 Chapter 14: The inline disease 508 Chapter 15: The inline disease
433 509
434There appears to be a common misperception that gcc has a magic "make me 510There appears to be a common misperception that gcc has a magic "make me
435faster" speedup option called "inline". While the use of inlines can be 511faster" speedup option called "inline". While the use of inlines can be
@@ -457,7 +533,7 @@ something it would have done anyway.
457 533
458 534
459 535
460 Chapter 15: References 536 Appendix I: References
461 537
462The C Programming Language, Second Edition 538The C Programming Language, Second Edition
463by Brian W. Kernighan and Dennis M. Ritchie. 539by Brian W. Kernighan and Dennis M. Ritchie.
@@ -481,4 +557,4 @@ Kernel CodingStyle, by greg@kroah.com at OLS 2002:
481http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ 557http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
482 558
483-- 559--
484Last updated on 30 December 2005 by a community effort on LKML. 560Last updated on 30 April 2006.