[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>

[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>
Randy Dunlap · Linus Torvalds
1 parent 3439dd86e3
Showing 1 changed file with 88 additions and 12 deletions Side-by-side Diff
Documentation/CodingStyle
@@ -155,8 +155,84 @@
 See next chapter.
  
  
-		Chapter 5: Functions
+		Chapter 5: Typedefs
  
+Please don't use things like "vps_t".
+
+It's a _mistake_ to use typedef for structures and pointers. When you see a
+
+	vps_t a;
+
+in the source, what does it mean?
+
+In contrast, if it says
+
+	struct virtual_container *a;
+
+you can actually tell what "a" is.
+
+Lots of people think that typedefs "help readability". Not so. They are
+useful only for:
+
+ (a) totally opaque objects (where the typedef is actively used to _hide_
+     what the object is).
+
+     Example: "pte_t" etc. opaque objects that you can only access using
+     the proper accessor functions.
+
+     NOTE! Opaqueness and "accessor functions" are not good in themselves.
+     The reason we have them for things like pte_t etc. is that there
+     really is absolutely _zero_ portably accessible information there.
+
+ (b) Clear integer types, where the abstraction _helps_ avoid confusion
+     whether it is "int" or "long".
+
+     u8/u16/u32 are perfectly fine typedefs, although they fit into
+     category (d) better than here.
+
+     NOTE! Again - there needs to be a _reason_ for this. If something is
+     "unsigned long", then there's no reason to do
+
+	typedef unsigned long myflags_t;
+
+     but if there is a clear reason for why it under certain circumstances
+     might be an "unsigned int" and under other configurations might be
+     "unsigned long", then by all means go ahead and use a typedef.
+
+ (c) when you use sparse to literally create a _new_ type for
+     type-checking.
+
+ (d) New types which are identical to standard C99 types, in certain
+     exceptional circumstances.
+
+     Although it would only take a short amount of time for the eyes and
+     brain to become accustomed to the standard types like 'uint32_t',
+     some people object to their use anyway.
+
+     Therefore, the Linux-specific 'u8/u16/u32/u64' types and their
+     signed equivalents which are identical to standard types are
+     permitted -- although they are not mandatory in new code of your
+     own.
+
+     When editing existing code which already uses one or the other set
+     of types, you should conform to the existing choices in that code.
+
+ (e) Types safe for use in userspace.
+
+     In certain structures which are visible to userspace, we cannot
+     require C99 types and cannot use the 'u32' form above. Thus, we
+     use __u32 and similar types in all structures which are shared
+     with userspace.
+
+Maybe there are other cases too, but the rule should basically be to NEVER
+EVER use a typedef unless you can clearly match one of those rules.
+
+In general, a pointer, or a struct that has elements that can reasonably
+be directly accessed should _never_ be a typedef.
+
+
+		Chapter 6: Functions
+
 Functions should be short and sweet, and do just one thing.  They should
 fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
 as we all know), and do one thing and do that well.
@@ -183,7 +259,7 @@
 to understand what you did 2 weeks from now.
  
  
-		Chapter 6: Centralized exiting of functions
+		Chapter 7: Centralized exiting of functions
  
 Albeit deprecated by some people, the equivalent of the goto statement is
 used frequently by compilers in form of the unconditional jump instruction.
@@ -220,7 +296,7 @@
 	return result;
 }
  
-		Chapter 7: Commenting
+		Chapter 8: Commenting
  
 Comments are good, but there is also a danger of over-commenting.  NEVER
 try to explain HOW your code works in a comment: it's much better to
@@ -240,7 +316,7 @@
 See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
 for details.
  
-		Chapter 8: You've made a mess of it
+		Chapter 9: You've made a mess of it
  
 That's OK, we all do.  You've probably been told by your long-time Unix
 user helper that "GNU emacs" automatically formats the C sources for
@@ -288,7 +364,7 @@
 remember: "indent" is not a fix for bad programming.
  
  
-		Chapter 9: Configuration-files
+		Chapter 10: Configuration-files
  
 For configuration options (arch/xxx/Kconfig, and all the Kconfig files),
 somewhat different indentation is used.
@@ -313,7 +389,7 @@
 experimental options should be denoted (EXPERIMENTAL).
  
  
-		Chapter 10: Data structures
+		Chapter 11: Data structures
  
 Data structures that have visibility outside the single-threaded
 environment they are created and destroyed in should always have
@@ -344,7 +420,7 @@
 have a reference count on it, you almost certainly have a bug.
  
  
-		Chapter 11: Macros, Enums and RTL
+		Chapter 12: Macros, Enums and RTL
  
 Names of macros defining constants and labels in enums are capitalized.
  
@@ -399,7 +475,7 @@
 covers RTL which is used frequently with assembly language in the kernel.
  
  
-		Chapter 12: Printing kernel messages
+		Chapter 13: Printing kernel messages
  
 Kernel developers like to be seen as literate. Do mind the spelling
 of kernel messages to make a good impression. Do not use crippled
@@ -410,7 +486,7 @@
 Printing numbers in parentheses (%d) adds no value and should be avoided.
  
  
-		Chapter 13: Allocating memory
+		Chapter 14: Allocating memory
  
 The kernel provides the following general purpose memory allocators:
 kmalloc(), kzalloc(), kcalloc(), and vmalloc().  Please refer to the API
@@ -429,7 +505,7 @@
 language.
  
  
-		Chapter 14: The inline disease
+		Chapter 15: The inline disease
  
 There appears to be a common misperception that gcc has a magic "make me
 faster" speedup option called "inline". While the use of inlines can be
@@ -457,7 +533,7 @@
  
  
  
-		Chapter 15: References
+		Appendix I: References
  
 The C Programming Language, Second Edition
 by Brian W. Kernighan and Dennis M. Ritchie.
@@ -481,5 +557,5 @@
 http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
  
 --
-Last updated on 30 December 2005 by a community effort on LKML.
+Last updated on 30 April 2006.
...	...	@@ -155,8 +155,84 @@
155	155	See next chapter.
156	156
157	157
158		- Chapter 5: Functions
	158	+ Chapter 5: Typedefs
159	159
	160	+Please don't use things like "vps_t".
	161	+
	162	+It's a _mistake_ to use typedef for structures and pointers. When you see a
	163	+
	164	+ vps_t a;
	165	+
	166	+in the source, what does it mean?
	167	+
	168	+In contrast, if it says
	169	+
	170	+ struct virtual_container *a;
	171	+
	172	+you can actually tell what "a" is.
	173	+
	174	+Lots of people think that typedefs "help readability". Not so. They are
	175	+useful 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	+
	227	+Maybe there are other cases too, but the rule should basically be to NEVER
	228	+EVER use a typedef unless you can clearly match one of those rules.
	229	+
	230	+In general, a pointer, or a struct that has elements that can reasonably
	231	+be directly accessed should _never_ be a typedef.
	232	+
	233	+
	234	+ Chapter 6: Functions
	235	+
160	236	Functions should be short and sweet, and do just one thing. They should
161	237	fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
162	238	as we all know), and do one thing and do that well.
...	...	@@ -183,7 +259,7 @@
183	259	to 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
188	264	Albeit deprecated by some people, the equivalent of the goto statement is
189	265	used frequently by compilers in form of the unconditional jump instruction.
...	...	@@ -220,7 +296,7 @@
220	296	return result;
221	297	}
222	298
223		- Chapter 7: Commenting
	299	+ Chapter 8: Commenting
224	300
225	301	Comments are good, but there is also a danger of over-commenting. NEVER
226	302	try to explain HOW your code works in a comment: it's much better to
...	...	@@ -240,7 +316,7 @@
240	316	See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
241	317	for 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
245	321	That's OK, we all do. You've probably been told by your long-time Unix
246	322	user helper that "GNU emacs" automatically formats the C sources for
...	...	@@ -288,7 +364,7 @@
288	364	remember: "indent" is not a fix for bad programming.
289	365
290	366
291		- Chapter 9: Configuration-files
	367	+ Chapter 10: Configuration-files
292	368
293	369	For configuration options (arch/xxx/Kconfig, and all the Kconfig files),
294	370	somewhat different indentation is used.
...	...	@@ -313,7 +389,7 @@
313	389	experimental options should be denoted (EXPERIMENTAL).
314	390
315	391
316		- Chapter 10: Data structures
	392	+ Chapter 11: Data structures
317	393
318	394	Data structures that have visibility outside the single-threaded
319	395	environment they are created and destroyed in should always have
...	...	@@ -344,7 +420,7 @@
344	420	have 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
349	425	Names of macros defining constants and labels in enums are capitalized.
350	426
...	...	@@ -399,7 +475,7 @@
399	475	covers 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
404	480	Kernel developers like to be seen as literate. Do mind the spelling
405	481	of kernel messages to make a good impression. Do not use crippled
...	...	@@ -410,7 +486,7 @@
410	486	Printing 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
415	491	The kernel provides the following general purpose memory allocators:
416	492	kmalloc(), kzalloc(), kcalloc(), and vmalloc(). Please refer to the API
...	...	@@ -429,7 +505,7 @@
429	505	language.
430	506
431	507
432		- Chapter 14: The inline disease
	508	+ Chapter 15: The inline disease
433	509
434	510	There appears to be a common misperception that gcc has a magic "make me
435	511	faster" speedup option called "inline". While the use of inlines can be
...	...	@@ -457,7 +533,7 @@
457	533
458	534
459	535
460		- Chapter 15: References
	536	+ Appendix I: References
461	537
462	538	The C Programming Language, Second Edition
463	539	by Brian W. Kernighan and Dennis M. Ritchie.
...	...	@@ -481,5 +557,5 @@
481	557	http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/
482	558
483	559	--
484		-Last updated on 30 December 2005 by a community effort on LKML.
	560	+Last updated on 30 April 2006.