diff options
author | Randy Dunlap <rdunlap@xenotime.net> | 2006-06-23 05:05:58 -0400 |
---|---|---|
committer | Linus Torvalds <torvalds@g5.osdl.org> | 2006-06-23 10:43:08 -0400 |
commit | 226a6b84aaaf1fac7a5d41cf4e7387fd9ba895d5 (patch) | |
tree | f1d72ef1145ddbd108c2701e1154fb81e078adb3 /Documentation | |
parent | 3439dd86e34580384d3b58cf8d54a9283cd7a342 (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/CodingStyle | 100 |
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. | |||
155 | See next chapter. | 155 | See next chapter. |
156 | 156 | ||
157 | 157 | ||
158 | Chapter 5: Functions | 158 | Chapter 5: Typedefs |
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 | ||
159 | 235 | ||
160 | Functions should be short and sweet, and do just one thing. They should | 236 | Functions should be short and sweet, and do just one thing. They should |
161 | fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24, | 237 | 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 brilliant, but maybe you'd like | |||
183 | to understand what you did 2 weeks from now. | 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 | Albeit deprecated by some people, the equivalent of the goto statement is | 264 | Albeit deprecated by some people, the equivalent of the goto statement is |
189 | used frequently by compilers in form of the unconditional jump instruction. | 265 | used 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 | ||
225 | Comments are good, but there is also a danger of over-commenting. NEVER | 301 | Comments are good, but there is also a danger of over-commenting. NEVER |
226 | try to explain HOW your code works in a comment: it's much better to | 302 | 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, please use the kerneldoc format. | |||
240 | See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc | 316 | See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc |
241 | for details. | 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 | That's OK, we all do. You've probably been told by your long-time Unix | 321 | That's OK, we all do. You've probably been told by your long-time Unix |
246 | user helper that "GNU emacs" automatically formats the C sources for | 322 | user 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 | |||
288 | remember: "indent" is not a fix for bad programming. | 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 | For configuration options (arch/xxx/Kconfig, and all the Kconfig files), | 369 | For configuration options (arch/xxx/Kconfig, and all the Kconfig files), |
294 | somewhat different indentation is used. | 370 | somewhat different indentation is used. |
@@ -313,7 +389,7 @@ support for file-systems, for instance) should be denoted (DANGEROUS), other | |||
313 | experimental options should be denoted (EXPERIMENTAL). | 389 | experimental options should be denoted (EXPERIMENTAL). |
314 | 390 | ||
315 | 391 | ||
316 | Chapter 10: Data structures | 392 | Chapter 11: Data structures |
317 | 393 | ||
318 | Data structures that have visibility outside the single-threaded | 394 | Data structures that have visibility outside the single-threaded |
319 | environment they are created and destroyed in should always have | 395 | environment 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 | |||
344 | have a reference count on it, you almost certainly have a bug. | 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 | Names of macros defining constants and labels in enums are capitalized. | 425 | Names 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 | |||
399 | covers RTL which is used frequently with assembly language in the kernel. | 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 | Kernel developers like to be seen as literate. Do mind the spelling | 480 | Kernel developers like to be seen as literate. Do mind the spelling |
405 | of kernel messages to make a good impression. Do not use crippled | 481 | of 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. | |||
410 | Printing numbers in parentheses (%d) adds no value and should be avoided. | 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 | The kernel provides the following general purpose memory allocators: | 491 | The kernel provides the following general purpose memory allocators: |
416 | kmalloc(), kzalloc(), kcalloc(), and vmalloc(). Please refer to the API | 492 | kmalloc(), 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 | |||
429 | language. | 505 | language. |
430 | 506 | ||
431 | 507 | ||
432 | Chapter 14: The inline disease | 508 | Chapter 15: The inline disease |
433 | 509 | ||
434 | There appears to be a common misperception that gcc has a magic "make me | 510 | There appears to be a common misperception that gcc has a magic "make me |
435 | faster" speedup option called "inline". While the use of inlines can be | 511 | faster" 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 | ||
462 | The C Programming Language, Second Edition | 538 | The C Programming Language, Second Edition |
463 | by Brian W. Kernighan and Dennis M. Ritchie. | 539 | by Brian W. Kernighan and Dennis M. Ritchie. |
@@ -481,4 +557,4 @@ Kernel CodingStyle, by greg@kroah.com at OLS 2002: | |||
481 | http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/ | 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. |