From 0e485dd005f38183e4c8c3e1b1baacf865c509b9 Mon Sep 17 00:00:00 2001 From: mark Date: Mon, 7 Feb 2000 17:20:48 +0000 Subject: [PATCH] Moved to the codingstd directory. --- doc/format.hfile | 141 ------------------ doc/format.srcfile | 134 ----------------- doc/format.srcfile.c | 96 ------------- doc/format.srcfile.html | 311 ---------------------------------------- doc/linux.CodingStyle | 212 --------------------------- 5 files changed, 894 deletions(-) delete mode 100644 doc/format.hfile delete mode 100644 doc/format.srcfile delete mode 100644 doc/format.srcfile.c delete mode 100644 doc/format.srcfile.html delete mode 100644 doc/linux.CodingStyle diff --git a/doc/format.hfile b/doc/format.hfile deleted file mode 100644 index d588262..0000000 --- a/doc/format.hfile +++ /dev/null @@ -1,141 +0,0 @@ -/* aheader.h: [one line description of the file] -* -------------------------------------------------------------------- -* -* [Project Name] -* -* [License Statement, eg. -* The contents of this file are subject to the Mozilla Public -* License Version 1.0 (the "License"); you may not use this file -* except in compliance with the License. You may obtain a copy of -* the License at http://www.mozilla.org/MPL/ ] -* -* [Warranty Statement, eg. -* Software distributed under the License is distributed on an "AS -* IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or -* implied. See the License for the specific language governing -* rights and limitations under the License. ] -* -* [Author contact, eg. -* The initial developer of the original code is Mark S. Mathews -* < mark@absoval.com >. Portions created by Mark S. Mathews -* are Copyright (C) 1998 AbsoluteValue Software, Inc. All -* Rights Reserved. ] -* -* [Change History] -* -* [Verbose Description] -* -* [Implementation and usage notes] -* -* [References] -* -* -------------------------------------------------------------------- -*/ - -#ifndef _AHEADER_H -#define _AHEADER_H - -/*=============================================================*/ -/*------ Constants --------------------------------------------*/ - -/*--- Fixed memory offsets --------------------------*/ -#define SU_OFF_LAST_TXDESC 0x3ec -#define SU_OFF_RSVD1 0x400 -#define SU_OFF_BANNER 0x480 -#define SU_OFF_CMD_BLK 0x4a0 -#define SU_OFF_CNTL_STATUS_BLK 0x4f0 -#define SU_OFF_VBM 0x500 -#define SU_OFF_BUFFER 0x600 - -/*--- Global Sizes ----------------------------------*/ -#define SU_LEN_BANNER 32 - - - -/*=============================================================*/ -/*------ Macros -----------------------------------------------*/ - -/*--- next testing macro (applies to Rx and Tx) -------*/ -#define SUTXD_ISLAST(x) ((x) & BIT31) -#define SURXD_ISLAST(x) ((x) & BIT31) - - -/*=============================================================*/ -/*------ Types and their related constants --------------------*/ - -/*--- Last Completed Tx Descriptor Block ---------------*/ -__WLAN_PRAGMA_PACK1__ -typedef struct am930txcmplt_blk -{ - volatile UINT32 last_bcast __WLAN_ATTRIB_PACK__; - volatile UINT32 last_mgmt __WLAN_ATTRIB_PACK__; - volatile UINT32 last_data __WLAN_ATTRIB_PACK__; - volatile UINT32 last_pspoll __WLAN_ATTRIB_PACK__; - volatile UINT32 last_cfpoll __WLAN_ATTRIB_PACK__; -} am930txcmplt_blk_t; -__WLAN_PRAGMA_PACKDFLT__ - -#define TXCMPLT_OFF_BCAST 0 -#define TXCMPLT_OFF_MGMT 4 -#define TXCMPLT_OFF_DATA 8 -#define TXCMPLT_OFF_PSPOLL 12 -#define TXCMPLT_OFF_CFPOLL 16 - -typedef void (*am930hw_scan_callback_t)(void *); - -/*=============================================================*/ -/*--- Function Declarations -----------------------------------*/ -/*=============================================================*/ -/* public: */ -am930hw_t* -am930hw_construct(UINT32 irq, UINT32 iobase, - UINT32 membase, am930mac_t *mac); - -void -am930hw_destruct(am930hw_t *hw); - -int -am930hw_init_rx_tx( am930hw_t *hw ); - -void -am930hw_ISR( am930hw_t *hw ); - -UINT32 -am930hw_joinbss( am930hw_t *hw, UINT32 ch, UINT32 newBSS, - UINT8 *bssid, wlan_ie_ssid_t *ssid, UINT32 bcn_int, - wlan_bss_ts_t ts, UINT32 sutro_ref_time ); - -UINT32 -am930hw_scan( am930hw_t *hw, UINT32 cntl, UINT8 *bssid, - UINT32 ch, UINT32 duration, - am930hw_scan_callback_t cb, void *callback_arg ); - -UINT32 -am930hw_reset( am930hw_t *hw ); - -/*=============================================================*/ -/*--- Inline Function Definitions (if supported) --------------*/ -/*=============================================================*/ - -/*---------------------------------------------------------------- -* am930hw_reset -* -* Perform reset of am930 part and test for valid operation -* operation following reset. -* -* returns: zero on success, non-zero if part fails to come up -* after reset. -----------------------------------------------------------------*/ -__INLINE__ UINT32 am930hw_reset( am930hw_t* hw) -{ - UINT32 result = 0; - - /* perform reset */ - /* test part */ - return result; -} - -#endif /* _AHEADER_H */ - - - diff --git a/doc/format.srcfile b/doc/format.srcfile deleted file mode 100644 index 69a7b7c..0000000 --- a/doc/format.srcfile +++ /dev/null @@ -1,134 +0,0 @@ - -
-/* asource.c: [one line description of file]
-*    --------------------------------------------------------------------
-*
-*   [Project Name]
-*
-*   [License Statement, eg.
-*   The contents of this file are subject to the Mozilla Public
-*   License Version 1.0 (the "License"); you may not use this file
-*   except in compliance with the License. You may obtain a copy of
-*   the License at http://www.mozilla.org/MPL/ ]
-*
-*   [Warranty Statement, eg.
-*   Software distributed under the License is distributed on an "AS
-*   IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
-*   implied. See the License for the specific language governing
-*   rights and limitations under the License. ]
-*
-*   [Author contact, eg.
-*   The initial developer of the original code is Mark S. Mathews
-*   < mark@absoval.com >.  Portions created by Mark S. Mathews
-*   are Copyright (C) 1998 AbsoluteValue Software, Inc.  All
-*   Rights Reserved. ]
-*
-*   [Change History]
-*
-*   [Verbose Description]
-*
-*   [Implementation and usage notes]
-*
-*   [References]
-*
-*    --------------------------------------------------------------------
-*/
-
-/* Portability/Compatibility header */
-#include <wlan/wlan_compat.h>
-
-/* The following prevents "kernel_version" from being set in this file. */
-#define __NO_VERSION__
-
-/* Non-project specific includes */
-/* PCMCIA headers generated during PCMCIA package installation */
-#include <pcmcia/config.h>
-#include <pcmcia/k_compat.h>
-
-/* Module related headers, non-module drivers should not include */
-#include <linux/version.h>
-
-#include <assert.h>
-#include <linux/delay.h>
-#include <linux/kernel.h>
-#include <linux/types.h>
-#include <linux/fcntl.h>
-#include <linux/interrupt.h>
-#include <linux/ptrace.h>
-#include <linux/ioport.h>
-#include <linux/in.h>
-#include <linux/malloc.h>
-#include <linux/string.h>
-#include <linux/timer.h>
-#include <asm/system.h>
-#include <asm/bitops.h>
-#include <asm/io.h>
-#include <linux/errno.h>
-
-/* Project Includes */
-#include <wlan/version.h>
-#include <wlan/am930mib.h>
-#include <wlan/p80211hdr.h>
-#include <wlan/p80211mgmt.h>
-#include <wlan/wlan_ioctl.h>
-#include <wlan/wlan_stable.h>
-#include "am930di.h"
-#include "am930llc.h"
-#include "am930mac.h"
-#include "am930hw.h"
-#include "am930mgr.h"
-
-/*====================================================================*/
-/* Local Constants                                                    */
-/*====================================================================*/
-
-#define ACONSTANT    22
-
-
-/*====================================================================*/
-/* Local Types                                                        */
-/*====================================================================*/
-
-typdef struct atype
-{
-    struct atype *next;
-    struct atype *prev;
-} atype_t;
-
-
-/*====================================================================*/
-/* Static data defined in this file                                   */
-/*====================================================================*/
-
-UINT8    wepkey[WLAN_WEP_NKEYS][WLAN_WEP_KEYLEN] =
-{
-    { 0xf1, 0x10, 0xec, 0xe0, 0xdc },
-    { 0x0f, 0xf2, 0x04, 0x09, 0xfb },
-    { 0x13, 0x37, 0xf2, 0xf9, 0x2d },
-    { 0xe9, 0x17, 0x19, 0x63, 0xc7 }
-};
-
-
-/*====================================================================*/
-/* Local Function Declarations                                        */
-/*====================================================================*/
-
-static void am930mgr_authen1_rx( am930mgr_t *mgr, wlan_fr_authen_t *f );
-static void am930mgr_authen2_rx( am930mgr_t *mgr, wlan_fr_authen_t *f );
-static void am930mgr_authen3_rx( am930mgr_t *mgr, wlan_fr_authen_t *f );
-static void am930mgr_authen4_rx( am930mgr_t *mgr, wlan_fr_authen_t *f );
-
-/*====================================================================*/
-/* Function Definitions                                               */
-/*====================================================================*/
-
-
-/*----------------------------------------------------------------
-*    am930mgr_assoc_begin_sta
-*
-*    Start the station association procedure.  Namely, send an
-*    association request frame to the AP.
-*
-*    returns: nothing for now
-----------------------------------------------------------------*/
-void am930mgr_assoc_begin_sta(am930mgr_t *mgr)
diff --git a/doc/format.srcfile.c b/doc/format.srcfile.c
deleted file mode 100644
index 81da101..0000000
--- a/doc/format.srcfile.c
+++ /dev/null
@@ -1,96 +0,0 @@
-/* [filename]: [one line description of the file]
-* --------------------------------------------------------------------
-*
-* Linux WLAN 
-*
-* The contents of this file are subject to the Mozilla Public
-* License Version 1.0 (the "License"); you may not use this file
-* except in compliance with the License. You may obtain a copy of
-* the License at http://www.mozilla.org/MPL/
-*
-* Software distributed under the License is distributed on an "AS
-* IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
-* implied. See the License for the specific language governing
-* rights and limitations under the License.
-*
-* The initial developer of the original code is Mark S. Mathews
-* .  Portions created by Mark S. Mathews
-* are Copyright (C) 1998 AbsoluteValue Software, Inc.  All Rights Reserved.
-*   
-* --------------------------------------------------------------------
-*
-* The initial author may be reached as mark@absoval.com, or 
-* C/O AbsoluteValue Software Inc., P.O. Box 941149, 
-* Maitland, FL, 32794-1149
-*
-* --------------------------------------------------------------------
-*
-* [File Description]
-*
-* [Implementation and Usage Notes] 
-*
-* --------------------------------------------------------------------
-*/
-
-/*================================================================*/
-/* System Includes */
-
-
-/*================================================================*/
-/* Project Includes */
-
-
-/*================================================================*/
-/* Local Constants */
-
-
-/*================================================================*/
-/* Local Macros */
-
-
-/*================================================================*/
-/* Local Types */
-
-
-/*================================================================*/
-/* Local Static Definitions */
-
-/*----------------------------------------------------------------*/
-/* --A subsection */
-
-
-/*================================================================*/
-/* Local Function Declarations */
-
-
-/*----------------------------------------------------------------
-* [function name]
-*
-* [Description]
-*
-* Arguments:
-*	[arglist]
-*
-* Returns: 
-*	[retlist]
-*
-* Side effects:
-*	[desc]
-*
-* Call context:
-*	[desc]
-----------------------------------------------------------------*/
-int afunction(void)
-{
-        DBFENTER;
-
-        if ( a ) {
-                prinf("xxx");
-        }
-
-
-        DBFEXIT;
-        return 0;
-}
-
-
diff --git a/doc/format.srcfile.html b/doc/format.srcfile.html
deleted file mode 100644
index c2ba914..0000000
--- a/doc/format.srcfile.html
+++ /dev/null
@@ -1,311 +0,0 @@
-
-
-    AVS C Source file format
-
-
-
1. C Source file format

-

-The following defines the common C source file format for linux-wlan.
-Most of the C-code formatting rules come from the linux kernel
-document CodingStyle.
-
-
2. Characters and Code layout

-
2.1. Character Set

-

-For all source files, we'll stick to the US character set and avoid all 
-trigraphs.
-
-
2.2. Indentation

-

-All indentation will be done using tab characters which are mapped to a 
-spacing of eight characters.
-
-
2.3. Braces

-

-Braces will be placed according to the format originally established
-in Kernighan and Ritchie's book "The C Programming Language".  Here
-are some example statements:
-

-
-
-for ( i= 0; i < N; i++) {
-   .
-   .
-   .
-}
-
-if ( a < b ) {
-   .
-   .
-   .
-} else {
-   .
-   .
-   .
-}
-
-do {
-   .
-   .
-   .
-} while ( i >> 0 );
-

-
-
-
-
3. Naming and Definition Conventions

-
-
3.1. Preprocessor Elements

-

-All elements defined via the C preprocessor (constants and macros) are
-named using all capital letters.  An exception is for macros that are
-either wrapping function calls for portability or for macros that are
-inline replacements for code that would normally be in a function.
-
-
3.2. Types

-

-All programmer defined types must have single word type names
-defined using the 
typedef
 statement.  All type names
-should be identified with an 
_t
 suffix.  This is
-particularly important for function pointers that are members of
-structures or arguments to functions.
-
-

-Anonymous types are not allowed.  All struct, union, and enum
-types shall be named and typedef'd.
-
-
-
3.3. Variables

-The following conventions should be followed for variable
-declaration and naming:
-	
    
-		
  • Variables should be named using meaningful names.
-		
  • Avoid variables with static lifetimes.
-		
  • If static lifetime variables must be used, use file
-		scoped static variables and avoid static lifetime
-		variables with visibility beyond file scope. 
-		
  • All static lifetime variables should be declared in
-		the "Local Statics" section near the top of a given
-		source file.
-	

-
-
3.4. Functions

-The following conventions should be followed for function
-declaration and definition:
-	
    
-		
  • All functions must be declared above the point
-		where they are called.
-		
  • Any functions that are only intended to be called
-		within a given source file should be declared static
-		within that file.
-		
  • Functions defined within a common source file that are 
-		visible across source file boundaries should be named
-		using a prefix that is unique to that source file.
-	

-
-
4. File Layout

-
 
-Each file should be layed out using a common format.  The
-following shows a complete file with all its major sections.
-
-

-Each major section within the file is begun with a comment of the
-form:
-
-/*================================================================*/
-/* [Section Name] */
-

-
-

-Subsections within a major section are denoted using:
-
-/*----------------------------------------------------------------*/
-/*  [Subsection Name]  */
-

-
-

-

-
-/* [filename]: [one line description of the file]
-* --------------------------------------------------------------------
-*
-* [Project Name]
-*
-* [License Statement]
-*
-* [Warranty Statement]
-*
-* [Initial Author Statement]
-*   
-* --------------------------------------------------------------------
-*
-* [Initial Author Contact]
-*
-* --------------------------------------------------------------------
-*
-* [File Description]
-*
-* [Implementation and Usage Notes]
-*
-* --------------------------------------------------------------------
-*/
-
-/*================================================================*/
-/* System Includes */
-
-
-/*================================================================*/
-/* Project Includes */
-
-
-/*================================================================*/
-/* Local Constants */
-
-
-/*================================================================*/
-/* Local Macros */
-
-/*----------------------------------------------------------------*/
-/*  [A subsection]  */
-
-/*================================================================*/
-/* Local Types */
-
-
-/*================================================================*/
-/* Local Static Definitions */
-
-
-/*================================================================*/
-/* Local Function Declarations */
-
-
-/*================================================================*/
-/* Function Definitions */
-
-

-

-
-
4.1. System  Includes Section

-

-Preprocessor #include statements that are including
-system includes shall be placed in this section.  System
-includes are those include files that are not part of the
-managed source for this project.
-
-
4.2. Project Includes Section

-

-Preprocessor #include statements that are including
-project includes shall be placed in this section.  Project 
-includes are those include files that are a part of the
-managed source for this project.
-
-
4.3. Local Constants Section

-

-Preprocessor "manifest" constants that are local to this file shall be
-placed in this section.  "Manifest" constants are preprocessor macros
-that take no arguments.
-
-
4.4. Local Macros Section

-

-Proprocessor macros that accept arguments shall be placed in this
-section.
-
-
4.5. Local Types Section

-

-Programmer defined types that are only used within the scope of this
-file shall be defined in this section.  Programmer defined types that
-are used in more than one source file should be defined in a header
-file.
-
-
4.6. Local Static Definitions Section

-

-Variables with static extent that are defined within this file shall
-be placed in this section.  Whether a variable has scope beyond this
-file will be apparent based on the presence or absence of the
-static keyword in the declaration.  If a variable is
-declared without the static keyword, there should be an
-extern declaration for that variable in a header file.
-
-
4.6. Local Function Declarations Section

-

-Functions that are only used within this file should be declared
-(prototyped) in this section.  Additionally, these functions should be
-declared using the static keyword.  This avoids polluting
-the global namespace with function names that need not be
-extern.
-
-

-Any functions defined in this file that are called from outside
-this file should be declared (prototyped) in a header file.
-
-
4.6. Function Definitions Section

-

-This section contains the definitions of the functions in this file.
-Each function (or group of strongly related functions) will be
-preceded by a function header comment (see below).
-
-
5. Comments

-
5.1. File Header

-

-Each source file will have a header comment containing information
-about the file as a whole.  That comment shall be formatted:
-

-
-/* [filename]: [one line description of the file]
-* --------------------------------------------------------------------
-*
-* [Project Name]
-*
-* [License Statement]
-*
-* [Warranty Statement]
-*
-* [Initial Author Statement]
-*   
-* --------------------------------------------------------------------
-*
-* [Initial Author Contact]
-*
-* --------------------------------------------------------------------
-*
-* [File Description]
-*
-* [Implementation and Usage Notes]
-*
-* --------------------------------------------------------------------
-*/
-

-

-
-
5.2. Function Header

-

-Each function (or group of closely related functions) will be preceded 
-by a function comment header.  The Side effects and
-Call context sections are optional.
-

-
-/*----------------------------------------------------------------
-* [function name]
-*
-* [description]
-*
-* Arguments:
-*	[argument list]
-*
-* Returns: 
-*	[return value list]
-*
-* Side effects:
-*	[description of function side effects]
-*
-* Call context:
-*	[description of calling context]
-----------------------------------------------------------------*/
-

-

-
-
-
-
-
diff --git a/doc/linux.CodingStyle b/doc/linux.CodingStyle
deleted file mode 100644
index edba246..0000000
--- a/doc/linux.CodingStyle
+++ /dev/null
@@ -1,212 +0,0 @@
-
-		Linux kernel coding style 
-
-This is a short document describing the preferred coding style for the
-linux kernel.  Coding style is very personal, and I won't _force_ my
-views on anybody, but this is what goes for anything that I have to be
-able to maintain, and I'd prefer it for most other things too.  Please
-at least consider the points made here. 
-
-First off, I'd suggest printing out a copy of the GNU coding standards,
-and NOT read it.  Burn them, it's a great symbolic gesture. 
-
-Anyway, here goes:
-
-
-	 	Chapter 1: Indentation
-
-Tabs are 8 characters, and thus indentations are also 8 characters. 
-There are heretic movements that try to make indentations 4 (or even 2!)
-characters deep, and that is akin to trying to define the value of PI to
-be 3. 
-
-Rationale: The whole idea behind indentation is to clearly define where
-a block of control starts and ends.  Especially when you've been looking
-at your screen for 20 straight hours, you'll find it a lot easier to see
-how the indentation works if you have large indentations. 
-
-Now, some people will claim that having 8-character indentations makes
-the code move too far to the right, and makes it hard to read on a
-80-character terminal screen.  The answer to that is that if you need
-more than 3 levels of indentation, you're screwed anyway, and should fix
-your program. 
-
-In short, 8-char indents make things easier to read, and have the added
-benefit of warning you when you're nesting your functions too deep. 
-Heed that warning. 
-
-
-		Chapter 2: Placing Braces
-
-The other issue that always comes up in C styling is the placement of
-braces.  Unlike the indent size, there are few technical reasons to
-choose one placement strategy over the other, but the preferred way, as
-shown to us by the prophets Kernighan and Ritchie, is to put the opening
-brace last on the line, and put the closing brace first, thusly:
-
-	if (x is true) {
-		we do y
-	}
-
-However, there is one special case, namely functions: they have the
-opening brace at the beginning of the next line, thus:
-
-	int function(int x)
-	{
-		body of function
-	}
-
-Heretic people all over the world have claimed that this inconsistency
-is ...  well ...  inconsistent, but all right-thinking people know that
-(a) K&R are _right_ and (b) K&R are right.  Besides, functions are
-special anyway (you can't nest them in C). 
-
-Note that the closing brace is empty on a line of its own, _except_ in
-the cases where it is followed by a continuation of the same statement,
-ie a "while" in a do-statement or an "else" in an if-statement, like
-this:
-
-	do {
-		body of do-loop
-	} while (condition);
-
-and
-
-	if (x == y) {
-		..
-	} else if (x > y) {
-		...
-	} else {
-		....
-	}
-			
-Rationale: K&R. 
-
-Also, note that this brace-placement also minimizes the number of empty
-(or almost empty) lines, without any loss of readability.  Thus, as the
-supply of new-lines on your screen is not a renewable resource (think
-25-line terminal screens here), you have more empty lines to put
-comments on. 
-
-
-		Chapter 3: Naming
-
-C is a Spartan language, and so should your naming be.  Unlike Modula-2
-and Pascal programmers, C programmers do not use cute names like
-ThisVariableIsATemporaryCounter.  A C programmer would call that
-variable "tmp", which is much easier to write, and not the least more
-difficult to understand. 
-
-HOWEVER, while mixed-case names are frowned upon, descriptive names for
-global variables are a must.  To call a global function "foo" is a
-shooting offense. 
-
-GLOBAL variables (to be used only if you _really_ need them) need to
-have descriptive names, as do global functions.  If you have a function
-that counts the number of active users, you should call that
-"count_active_users()" or similar, you should _not_ call it "cntusr()". 
-
-Encoding the type of a function into the name (so-called Hungarian
-notation) is brain damaged - the compiler knows the types anyway and can
-check those, and it only confuses the programmer.  No wonder MicroSoft
-makes buggy programs. 
-
-LOCAL variable names should be short, and to the point.  If you have
-some random integer loop counter, it should probably be called "i". 
-Calling it "loop_counter" is non-productive, if there is no chance of it
-being mis-understood.  Similarly, "tmp" can be just about any type of
-variable that is used to hold a temporary value. 
-
-If you are afraid to mix up your local variable names, you have another
-problem, which is called the function-growth-hormone-imbalance syndrome. 
-See next chapter. 
-
-		
-		Chapter 4: 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. 
-
-The maximum length of a function is inversely proportional to the
-complexity and indentation level of that function.  So, if you have a
-conceptually simple function that is just one long (but simple)
-case-statement, where you have to do lots of small things for a lot of
-different cases, it's OK to have a longer function. 
-
-However, if you have a complex function, and you suspect that a
-less-than-gifted first-year high-school student might not even
-understand what the function is all about, you should adhere to the
-maximum limits all the more closely.  Use helper functions with
-descriptive names (you can ask the compiler to in-line them if you think
-it's performance-critical, and it will probably do a better job of it
-that you would have done). 
-
-Another measure of the function is the number of local variables.  They
-shouldn't exceed 5-10, or you're doing something wrong.  Re-think the
-function, and split it into smaller pieces.  A human brain can
-generally easily keep track of about 7 different things, anything more
-and it gets confused.  You know you're brilliant, but maybe you'd like
-to understand what you did 2 weeks from now. 
-
-
-		Chapter 5: 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
-write the code so that the _working_ is obvious, and it's a waste of
-time to explain badly written code. 
-
-Generally, you want your comments to tell WHAT your code does, not HOW. 
-Also, try to avoid putting comments inside a function body: if the
-function is so complex that you need to separately comment parts of it,
-you should probably go back to chapter 4 for a while.  You can make
-small comments to note or warn about something particularly clever (or
-ugly), but try to avoid excess.  Instead, put the comments at the head
-of the function, telling people what it does, and possibly WHY it does
-it. 
-
-
-		Chapter 6: 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
-you, and you've noticed that yes, it does do that, but the defaults it
-uses are less than desirable (in fact, they are worse than random
-typing - a infinite number of monkeys typing into GNU emacs would never
-make a good program). 
-
-So, you can either get rid of GNU emacs, or change it to use saner
-values.  To do the latter, you can stick the following in 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 c-basic-offset 8))
-
-This will define the M-x linux-c-mode command.  When hacking on a
-module, if you put the string -*- linux-c -*- somewhere on the first
-two lines, this mode will be automatically invoked. Also, you may want
-to add
-
-(setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode)
-                       auto-mode-alist))
-
-to your .emacs file if you want to have linux-c-mode switched on
-automagically when you edit source files under /usr/src/linux.
-
-But even if you fail in getting emacs to do sane formatting, not
-everything is lost: use "indent".
-
-Now, again, GNU indent has the same brain dead settings that GNU emacs
-has, which is why you need to give it a few command line options. 
-However, that's not too bad, because even the makers of GNU indent
-recognize the authority of K&R (the GNU people aren't evil, they are
-just severely misguided in this matter), so you just give indent the
-options "-kr -i8" (stands for "K&R, 8 character indents"). 
-
-"indent" has a lot of options, and especially when it comes to comment
-re-formatting you may want to take a look at the manual page.  But
-remember: "indent" is not a fix for bad programming.