The patch titled
CodingStyle: add typedefs chapter
has been removed from the -mm tree. Its filename is
codingstyle-add-typedefs-chapter.patch
This patch was dropped because it was merged into mainline or a subsystem tree
------------------------------------------------------
Subject: CodingStyle: add typedefs chapter
From: Randy Dunlap <rdunlap@xxxxxxxxxxxx>
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@xxxxxxxxxxxx>
Signed-off-by: Andrew Morton <akpm@xxxxxxxx>
---
Documentation/CodingStyle | 100 +++++++++++++++++++++++++++++++-----
1 file changed, 88 insertions(+), 12 deletions(-)
diff -puN Documentation/CodingStyle~codingstyle-add-typedefs-chapter Documentation/CodingStyle
--- a/Documentation/CodingStyle~codingstyle-add-typedefs-chapter
+++ a/Documentation/CodingStyle
@@ -155,7 +155,83 @@ problem, which is called the function-gr
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,
@@ -183,7 +259,7 @@ and it gets confused. You know you're b
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 @@ out:
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 @@ When commenting the kernel API functions
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 @@ re-formatting you may want to take a loo
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 @@ support for file-systems, for instance)
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 @@ Remember: if another thread can find you
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 @@ The cpp manual deals with macros exhaust
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 @@ Kernel messages do not have to be termin
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 @@ from void pointer to any other pointer t
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 @@ something it would have done anyway.
- Chapter 15: References
+ Appendix I: References
The C Programming Language, Second Edition
by Brian W. Kernighan and Dennis M. Ritchie.
@@ -481,4 +557,4 @@ Kernel CodingStyle, by greg@xxxxxxxxx at
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.
_
Patches currently in -mm which might be from rdunlap@xxxxxxxxxxxx are
origin.patch
git-dvb.patch
git-kbuild.patch
git-pcmcia.patch
lpfc-sparse-null-warnings.patch
aic7-cleanup-module_parm_desc-strings.patch
qla1280-fix-section-mismatch-warnings.patch
areca-raid-linux-scsi-driver.patch
git-watchdog.patch
add-poisonh-and-patch-primary-users.patch
update-2-drivers-for-poisonh.patch
poison-add-use-more-constants.patch
fix-listh-kernel-doc.patch
listh-doc-change-counter-to-control.patch
kernel-doc-drop-leading-space-in-sections.patch
kernel-doc-script-cleanups.patch
wd7000-fix-section-mismatch-warnings.patch
megaraid_mbox-fix-section-mismatch-warnings.patch
kernel-doc-mm-readhead-fixup.patch
checkstack-pirnt-module-names.patch
wan-sdla-section-fixes.patch
trident-fb-section-fixes.patch
cdrom-mcdx-section-fixes.patch
char-ip2-more-section-fixes-replacement.patch
advansys-section-fixes.patch
kernel-doc-warn-on-malformed-function-docs.patch
ide-floppy-fix-debug-only-syntax-error.patch
kernel-doc-for-lib-bitmapc.patch
kernel-doc-for-lib-cmdlinec.patch
kernel-doc-for-lib-crcc.patch
kernel-doc-dont-use-xml-escapes-in-text-or-man-output.patch
kernel-doc-use-members-for-struct-fields-consistently.patch
reed-solomon-fix-kernel-doc-comments.patch
ktime-hrtimer-fix-kernel-doc-comments.patch
dmi-cleanup-kernel-doc-add-to-docbook.patch
kthread-move-kernel-doc-and-put-it-into-docbook.patch
corrections-to-memory-barrier-doc.patch
parport-add-to-kernel-doc.patch
pi-futex-rt-mutex-docs-update.patch
acpi-identify-which-device-is-not-power-manageable.patch
-
To unsubscribe from this list: send the line "unsubscribe mm-commits" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
